변경 상태는 일정 기간 동안 계정 내에서 변경된 리소스를 추적하는 방법을 제공합니다. 특정 기간 동안 한 리소스에 여러 변경사항이 있는 경우 가장 최근의 변경사항만 반환됩니다. 그런 다음 로컬 데이터베이스 값을 기간 내에 변경된 값과 동기화해야 하는지 여부를 결정할 수 있습니다.
예를 들어 지정된 기간 동안 특정 캠페인을 추가한 후 업데이트하면 ADD
작업이 아닌 UPDATE
의 변경 상태만 반환됩니다. 기간의 끝을 업데이트 이전으로 옮기면 ADD
작업이 표시됩니다.
변경 내역 웹페이지와 유사한 세부정보 뷰가 있는 완전한 필드별 결과를 얻으려면 이벤트 변경을 참조하세요.
상태 유형 변경
다음 리소스 유형이 추적됩니다. 리소스 유형 ID는 ChangeStatusResourceType
의 열거형 값 색인과 다릅니다.
리소스 유형 | 값 | 리소스 유형 ID |
---|---|---|
핵심 항목 | ||
광고그룹 | AD_GROUP | 2 |
광고그룹 광고 | AD_GROUP_AD | 3 |
광고그룹 입찰가 조정 | AD_GROUP_BID_MODIFIER | 11 |
광고그룹 기준 | AD_GROUP_CRITERION | 4 |
광고그룹 피드 | AD_GROUP_FEED | 12 |
실행 | 캠페인 | 5 |
캠페인 기준 | CAMPAIGN_CRITERION | 6 |
피드 | ||
캠페인 피드 | CAMPAIGN_FEED | 9 |
피드 | 피드 | 8 |
피드 항목 | FEED_ITEM | 10 |
공유 세트 | ||
공유 조합 | SHARED_SET | 17 |
캠페인 공유 조합 | CAMPAIGN_SHARED_SET | 18 |
애셋 | ||
저작물 | 애셋 | 13 |
고객 애셋 | CUSTOMER_ASSET | 14 |
캠페인 확장 소재 | CAMPAIGN_ASSET | 15 |
광고그룹 애셋 | AD_GROUP_ASSET | 16 |
ID로 리소스 유형 결정
이전 API 버전의 경우 Google Ads API가 UNKNOWN
리소스 유형 값이 있는 행을 반환할 수 있습니다. 즉, 이 유형은 Google Ads API의 향후 버전에서는 지원되지만 현재 버전이 출시되었을 때는 완전히 지원되지 않았습니다. 이 경우에도 반환된 resource_name
를 파싱하여 행의 리소스 유형을 확인할 수 있습니다.
리소스 이름 형식은 다음과 같습니다.
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
-
문자로 구분된 하나 이상의 추가 ID가 있을 수 있지만 관련된 ID는 마지막 슬래시 뒤의 두 번째 ID인 resource_type_id
입니다. 이전 표에는 모든 리소스 유형 ID가 나와 있습니다.
변경사항 가져오기
변경사항 목록은 날짜 및 리소스 유형별로 필터링할 수 있습니다. 지정된 리소스에 대한 작업은 ADDED
, CHANGED
, REMOVED
중 하나입니다.
모든 리소스 유형의 모든 변경사항 목록을 검색할 수 있습니다. 반환된 resource_type
는 변경된 필드입니다. 모든 상위 필드도 채워집니다. 예를 들어 ad_group_criterion
이 변경되면 ad_group
필드도 채워집니다.
변경사항이 변경 상태 결과에 반영되기까지 최대 3분이 걸릴 수 있습니다.
쿼리는 지난 90일 이내의 날짜(선택적으로 시간)를 필터링해야 하며 최대 10,000개의 결과로 설정된 LIMIT
절을 포함해야 합니다.
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) { String query = "SELECT change_status.resource_name, " + "change_status.last_change_date_time, " + "change_status.resource_status, " + "change_status.resource_type, " + "change_status.ad_group, " + "change_status.ad_group_ad, " + "change_status.ad_group_bid_modifier, " + "change_status.ad_group_criterion, " + "change_status.ad_group_feed, " + "change_status.campaign, " + "change_status.campaign_criterion, " + "change_status.campaign_feed, " + "change_status.feed, " + "change_status.feed_item " + "FROM change_status " + "WHERE change_status.last_change_date_time DURING LAST_14_DAYS " + "ORDER BY change_status.last_change_date_time " + "LIMIT 10000"; try (GoogleAdsServiceClient client = googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) { SearchPagedResponse response = client.search(String.valueOf(customerId), query); for (GoogleAdsRow row : response.iterateAll()) { Optional<String> resourceNameOfChangedEntity = getResourceNameForResourceType(row.getChangeStatus()); System.out.printf( "On '%s', change status '%s' shows a resource type of '%s' " + "with resource name '%s' was '%s'.%n", row.getChangeStatus().getLastChangeDateTime(), row.getChangeStatus().getResourceName(), row.getChangeStatus().getResourceType().name(), resourceNameOfChangedEntity.orElse(""), row.getChangeStatus().getResourceStatus().name()); } } }
C#
public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V16.GoogleAdsService); string searchQuery = @" SELECT change_status.resource_name, change_status.last_change_date_time, change_status.resource_type, change_status.campaign, change_status.ad_group, change_status.resource_status, change_status.ad_group_ad, change_status.ad_group_criterion, change_status.campaign_criterion FROM change_status WHERE change_status.last_change_date_time DURING LAST_14_DAYS ORDER BY change_status.last_change_date_time LIMIT 10000"; // Create a request that will retrieve all changes using pages of the specified // page size. SearchGoogleAdsRequest request = new SearchGoogleAdsRequest() { PageSize = PAGE_SIZE, Query = searchQuery, CustomerId = customerId.ToString() }; try { // Issue the search request. PagedEnumerable<SearchGoogleAdsResponse, GoogleAdsRow> searchPagedResponse = googleAdsService.Search(request); // Iterate over all rows in all pages and prints the requested field values for the // campaign in each row. foreach (GoogleAdsRow googleAdsRow in searchPagedResponse) { Console.WriteLine("Last change: {0}, Resource type: {1}, " + "Resource name: {2}, Resource status: {3}, Specific resource name: {4}", googleAdsRow.ChangeStatus.LastChangeDateTime, googleAdsRow.ChangeStatus.ResourceType, googleAdsRow.ChangeStatus.ResourceName, googleAdsRow.ChangeStatus.ResourceStatus, SpecificResourceName(googleAdsRow.ChangeStatus.ResourceType, googleAdsRow)); } } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } } /// <summary> /// Return the name of the most specific resource that changed. /// </summary> /// <param name="resourceType">Type of the resource.</param> /// <param name="row">Each returned row contains all possible changed fields</param> /// <returns>The resource name of the changed field based on the resource type. /// The changed field's parent is also populated, but is not used.</returns> private string SpecificResourceName(ChangeStatusResourceType resourceType, GoogleAdsRow row) { string resourceName; switch (resourceType) { case ChangeStatusResourceType.AdGroup: resourceName = row.ChangeStatus.AdGroup; break; case ChangeStatusResourceType.AdGroupAd: resourceName = row.ChangeStatus.AdGroupAd; break; case ChangeStatusResourceType.AdGroupCriterion: resourceName = row.ChangeStatus.AdGroupCriterion; break; case ChangeStatusResourceType.Campaign: resourceName = row.ChangeStatus.Campaign; break; case ChangeStatusResourceType.CampaignCriterion: resourceName = row.ChangeStatus.CampaignCriterion; break; case ChangeStatusResourceType.Unknown: case ChangeStatusResourceType.Unspecified: default: resourceName = ""; break; } return resourceName; }
2,399필리핀
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId) { $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); // Creates a query to find information about changed resources in your account. $query = 'SELECT change_status.resource_name, ' . 'change_status.last_change_date_time, ' . 'change_status.resource_status, ' . 'change_status.resource_type, ' . 'change_status.ad_group, ' . 'change_status.ad_group_ad, ' . 'change_status.ad_group_bid_modifier, ' . 'change_status.ad_group_criterion, ' . 'change_status.ad_group_feed, ' . 'change_status.campaign, ' . 'change_status.campaign_criterion, ' . 'change_status.campaign_feed, ' . 'change_status.feed, ' . 'change_status.feed_item ' . 'FROM change_status ' . 'WHERE change_status.last_change_date_time DURING LAST_14_DAYS ' . 'ORDER BY change_status.last_change_date_time ' . 'LIMIT 10000'; // Issues a search request by specifying page size. $response = $googleAdsServiceClient->search( SearchGoogleAdsRequest::build($customerId, $query)->setPageSize(self::PAGE_SIZE) ); // Iterates over all rows in all pages and prints the requested field values for // the change status in each row. foreach ($response->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ printf( "On %s, change status '%s' shows resource '%s' with type '%s' and status '%s'.%s", $googleAdsRow->getChangeStatus()->getLastChangeDateTime(), $googleAdsRow->getChangeStatus()->getResourceName(), self::getResourceNameForResourceType($googleAdsRow->getChangeStatus()), ChangeStatusResourceType::name( $googleAdsRow->getChangeStatus()->getResourceType() ), ChangeStatusOperation::name($googleAdsRow->getChangeStatus()->getResourceStatus()), PHP_EOL ); } } /** * Gets the resource name for the resource type of the change status object. * * Each returned row contains all possible changed resources, only one of which is populated * with the name of the changed resource. This function returns the resource name of the * changed resource based on the resource type. * * @param ChangeStatus $changeStatus the change status object for getting changed resource * @return string the name of the resource that changed */ private static function getResourceNameForResourceType( ChangeStatus $changeStatus ) { $resourceType = $changeStatus->getResourceType(); $resourceName = ''; // Default value for UNSPECIFIED or UNKNOWN resource type. switch ($resourceType) { case ChangeStatusResourceType::AD_GROUP: $resourceName = $changeStatus->getAdGroup(); break; case ChangeStatusResourceType::AD_GROUP_AD: $resourceName = $changeStatus->getAdGroupAd(); break; case ChangeStatusResourceType::AD_GROUP_BID_MODIFIER: $resourceName = $changeStatus->getAdGroupBidModifier(); break; case ChangeStatusResourceType::AD_GROUP_CRITERION: $resourceName = $changeStatus->getAdGroupCriterion(); break; case ChangeStatusResourceType::AD_GROUP_FEED: $resourceName = $changeStatus->getAdGroupFeed(); break; case ChangeStatusResourceType::CAMPAIGN: $resourceName = $changeStatus->getCampaign(); break; case ChangeStatusResourceType::CAMPAIGN_CRITERION: $resourceName = $changeStatus->getCampaignCriterion(); break; case ChangeStatusResourceType::CAMPAIGN_FEED: $resourceName = $changeStatus->getCampaignFeed(); break; case ChangeStatusResourceType::FEED: $resourceName = $changeStatus->getFeed(); break; case ChangeStatusResourceType::FEED_ITEM: $resourceName = $changeStatus->getFeedItem(); break; } return $resourceName; }
Python
def main(client, customer_id): ads_service = client.get_service("GoogleAdsService") # Construct a query to find information about changed resources in your # account. query = """ SELECT change_status.resource_name, change_status.last_change_date_time, change_status.resource_type, change_status.campaign, change_status.ad_group, change_status.resource_status, change_status.ad_group_ad, change_status.ad_group_criterion, change_status.campaign_criterion FROM change_status WHERE change_status.last_change_date_time DURING LAST_14_DAYS ORDER BY change_status.last_change_date_time LIMIT 10000""" search_request = client.get_type("SearchGoogleAdsRequest") search_request.customer_id = customer_id search_request.query = query search_request.page_size = _DEFAULT_PAGE_SIZE response = ads_service.search(request=search_request) for row in response: cs = row.change_status resource_type = cs.resource_type.name if resource_type == "AD_GROUP": resource_name = cs.ad_group elif resource_type == "AD_GROUP_AD": resource_name = cs.ad_group_ad elif resource_type == "AD_GROUP_CRITERION": resource_name = cs.ad_group_criterion elif resource_type == "CAMPAIGN": resource_name = cs.campaign elif resource_type == "CAMPAIGN_CRITERION": resource_name = cs.campaign_criterion else: resource_name = "UNKNOWN" resource_status = cs.resource_status.name print( f"On '{cs.last_change_date_time}', change status " f"'{cs.resource_name}' shows that a resource type of " f"'{resource_type}' with resource name '{resource_name}' was " f"{resource_status}" )
Ruby
def get_change_summary(customer_id) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new # Construct a query to find information about changed resources in your # account. query = <<~QUERY SELECT change_status.resource_name, change_status.last_change_date_time, change_status.resource_type, change_status.campaign, change_status.ad_group, change_status.resource_status, change_status.ad_group_ad, change_status.ad_group_criterion, change_status.campaign_criterion FROM change_status WHERE change_status.last_change_date_time DURING LAST_14_DAYS ORDER BY change_status.last_change_date_time LIMIT 10000 QUERY # Execute the query. response = client.service.google_ads.search( customer_id: customer_id, query: query, page_size: PAGE_SIZE ) # Process the results. response.each do |row| cs = row.change_status resource_name = case cs.resource_type when :AD_GROUP cs.ad_group when :AD_GROUP_AD cs.ad_group_ad when :AD_GROUP_CRITERION cs.ad_group_criterion when :CAMPAIGN cs.campaign when :CAMPAIGN_CRITERION cs.campaign_criterion else "UNKNOWN" end puts "On #{cs.last_change_date_time}, change status #{cs.resource_name} " \ "shows a resource type of #{cs.resource_type} " \ "with resource name #{resource_name} was #{cs.resource_status}." end end
Perl
sub get_change_summary { my ($api_client, $customer_id) = @_; # Construct a search query to find information about changed resources in your # account. my $search_query = "SELECT change_status.resource_name, change_status.last_change_date_time, " . "change_status.resource_status, " . "change_status.resource_type, " . "change_status.ad_group, " . "change_status.ad_group_ad, " . "change_status.ad_group_bid_modifier, " . "change_status.ad_group_criterion, " . "change_status.ad_group_feed, " . "change_status.campaign, " . "change_status.campaign_criterion, " . "change_status.campaign_feed, " . "change_status.feed, " . "change_status.feed_item " . "FROM change_status " . "WHERE change_status.last_change_date_time DURING LAST_14_DAYS " . "ORDER BY change_status.last_change_date_time " . "LIMIT 10000"; # Create a search Google Ads request that will retrieve all change statuses using # pages of the specified page size. my $search_request = Google::Ads::GoogleAds::V16::Services::GoogleAdsService::SearchGoogleAdsRequest ->new({ customerId => $customer_id, query => $search_query, pageSize => PAGE_SIZE }); # Get the GoogleAdsService. my $google_ads_service = $api_client->GoogleAdsService(); my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({ service => $google_ads_service, request => $search_request }); # Iterate over all rows in all pages and print the requested field values for # the change status in each row. while ($iterator->has_next) { my $google_ads_row = $iterator->next; my $change_status = $google_ads_row->{changeStatus}; printf "On %s, change status '%s' shows a resource type of '%s' " . "with resource name '%s' was '%s'.\n", $change_status->{lastChangeDateTime}, $change_status->{resourceName}, $change_status->{resourceType}, __get_resource_name_for_resource_type($change_status), $change_status->{resourceStatus}; } return 1; } # This method returns the resource name of the changed field based on the # resource type. The changed field's parent is also populated but is not used. sub __get_resource_name_for_resource_type { my $change_status = shift; my $resource_type = $change_status->{resourceType}; if ($resource_type eq AD_GROUP) { return $change_status->{adGroup}; } elsif ($resource_type eq AD_GROUP_AD) { return $change_status->{adGroupAd}; } elsif ($resource_type eq AD_GROUP_BID_MODIFIER) { return $change_status->{adGroupBidModifier}; } elsif ($resource_type eq AD_GROUP_CRITERION) { return $change_status->{adGroupCriterion}; } elsif ($resource_type eq AD_GROUP_FEED) { return $change_status->{adGroupFeed}; } elsif ($resource_type eq CAMPAIGN) { return $change_status->{campaign}; } elsif ($resource_type eq CAMPAIGN_CRITERION) { return $change_status->{campaignCriterion}; } elsif ($resource_type eq CAMPAIGN_FEED) { return $change_status->{campaignFeed}; } elsif ($resource_type eq FEED) { return $change_status->{feed}; } elsif ($resource_type eq FEED_ITEM) { return $change_status->{feedItem}; } else { return ""; } }
로컬에서 동기화
정확한 resource_name
를 가져온 후에는 이 리소스 이름으로 새 쿼리를 실행하여 리소스의 모든 현재 값을 가져와야 합니다. 특정 리소스의 변경된 값에 대한 변경 상태는 추적되지 않고 변경된 리소스만 추적합니다. 이전 값과 현재 값의 차이를 결정하는 것은 호출 프로그램의 책임입니다.
시간 변경
last_change_date_time
필드는 가장 최근에 리소스가 변경된 시기를 나타냅니다. 따라서 로컬에 캐시된 데이터의 최신성을 이 필드의 값과 비교하여 로컬 데이터가 최신이 아닌지 확인할 수 있습니다.
이 필드는 필터링 가능합니다. 즉, Google Ads 쿼리 언어 (GAQL) 쿼리의 WHERE
절에서 사용할 수 있으므로 지정된 시간 이전 또는 이후에 발생한 리소스의 변경사항을 쿼리할 수 있습니다.
예를 들어 지난주에 특정 리소스 유형에 대해 발생한 모든 변경사항을 찾으려면 다음 GAQL 조건자 절을 사용하면 됩니다.
WHERE change_status.last_change_date_time DURING LAST_7_DAYS