Thay đổi trạng thái cung cấp cách thức để theo dõi những tài nguyên nào đã thay đổi trong tài khoản trong một khoảng thời gian nhất định. Nếu tài nguyên có nhiều thay đổi trong khoảng thời gian bạn chỉ định, thì chỉ thay đổi mới nhất sẽ được trả về. Sau đó, bạn có thể xác định xem mình có cần đồng bộ hoá các giá trị cơ sở dữ liệu cục bộ với những giá trị đã thay đổi trong khoảng thời gian đó.
Ví dụ: nếu trong một khoảng thời gian nhất định, bạn thêm rồi cập nhật một
chiến dịch, chỉ trạng thái thay đổi cho UPDATE
chứ không phải cho ADD
được trả về. Nếu bạn chuyển thời điểm kết thúc khung thời gian đến trước
cập nhật, thì bạn sẽ thấy thao tác ADD
.
Nếu bạn muốn kết quả theo từng trường hoàn chỉnh có chế độ xem chi tiết tương tự như trang web Nhật ký thay đổi, hãy xem bài viết Thay đổi sự kiện.
Thay đổi loại trạng thái
Tài nguyên sau đây
là
theo dõi. Lưu ý rằng mã loại tài nguyên khác với giá trị enum
chỉ số của
ChangeStatusResourceType
.
Loại tài nguyên | Giá trị | Mã loại tài nguyên |
---|---|---|
Các pháp nhân chính | ||
Nhóm quảng cáo | AD_GROUP | 2 |
Loại quảng cáo của nhóm quảng cáo | AD_GROUP_AD | 3 |
Hệ số sửa đổi giá thầu cho nhóm quảng cáo | AD_GROUP_BID_MODIFIER | 11 |
Tiêu chí nhóm quảng cáo | AD_GROUP_CRITERION | 4 |
Nguồn cấp dữ liệu của nhóm quảng cáo | AD_GROUP_FEED | 12 |
Nhóm thành phần quảng cáo | ASSET_BUNDLE | 19 |
Chiến dịch | CHIẾN DỊCH | 5 |
Tiêu chí chiến dịch | CAMPAIGN_CRITERION | 6 |
Nguồn cấp dữ liệu | ||
Nguồn cấp dữ liệu của chiến dịch | CAMPAIGN_FEED | 9 |
Nguồn cấp dữ liệu | NGUỒN CẤP DỮ LIỆU | 8 |
Mục nguồn cấp dữ liệu | FEED_ITEM | 10 |
Nhóm chia sẻ | ||
Nhóm chia sẻ | SHARED_SET | 17 |
Nhóm chia sẻ chiến dịch | CAMPAIGN_SHARED_SET | 18 |
Tài sản | ||
Thành phần | THÀNH PHẦN | 13 |
Thành phần của khách hàng | CUSTOMER_ASSET | 14 |
Thành phần của chiến dịch | CAMPAIGN_ASSET | 15 |
Thành phần nhóm quảng cáo | AD_GROUP_ASSET | 16 |
Xác định loại tài nguyên theo mã nhận dạng
API Google Ads có thể trả về các hàng có giá trị loại tài nguyên UNKNOWN
cho trước đó
Phiên bản API, nghĩa là loại này được hỗ trợ trong phiên bản tương lai của
API Google Ads nhưng chưa được hỗ trợ đầy đủ tại thời điểm phiên bản hiện tại của bạn được hỗ trợ
phát hành. Khi điều này xảy ra, bạn vẫn có thể xác định loại tài nguyên của
bằng cách phân tích cú pháp resource_name
được trả về.
Định dạng tên tài nguyên là:
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
Có thể có một hoặc nhiều mã nhận dạng bổ sung, được phân tách bằng ký tự -
, nhưng
mã có liên quan là resource_type_id
(mã nhận dạng thứ hai sau mã này)
dấu gạch chéo cuối cùng. Bảng trước liệt kê tất cả mã loại tài nguyên.
Truy xuất các thay đổi
Bạn có thể lọc danh sách các thay đổi theo ngày cũng như theo loại tài nguyên. Chiến lược phát hành đĩa đơn
trên một tài nguyên cụ thể là một trong
ADDED
!
CHANGED
,
hoặc
REMOVED
.
Bạn có thể truy xuất danh sách tất cả thay đổi đối với tất cả các loại tài nguyên. Được trả về
resource_type
là trường mà
đã thay đổi. Mọi trường gốc cũng được điền sẵn. Ví dụ: nếu
ad_group_criterion
đã thay đổi,
thì trường ad_group
cũng là
được điền sẵn.
Một thay đổi có thể mất tới 3 phút mới được phản ánh trong trạng thái thay đổi kết quả.
Truy vấn phải lọc theo ngày trong vòng 90 ngày qua và không bắt buộc phải lọc thời gian,
đồng thời phải chứa mệnh đề LIMIT
được đặt tối đa 10.000 kết quả.
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.V17.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. SearchGoogleAdsRequest request = new SearchGoogleAdsRequest() { 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; }
PHP
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. $response = $googleAdsServiceClient->search( SearchGoogleAdsRequest::build($customerId, $query) ); // 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 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::V17::Services::GoogleAdsService::SearchGoogleAdsRequest ->new({ customerId => $customer_id, query => $search_query }); # 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 ""; } }
Đồng bộ hoá cục bộ
Sau khi resource_name
chính xác là
hãy truy xuất một truy vấn mới có tên tài nguyên này để lấy tất cả
các giá trị hiện tại của tài nguyên. Trạng thái thay đổi không được theo dõi cho một
các giá trị đã thay đổi của tài nguyên—chỉ những tài nguyên đã thay đổi. Đang xác định
sự khác biệt giữa giá trị trước đó và giá trị hiện tại là trách nhiệm của
chương trình gọi điện.
Thay đổi thời gian
last_change_date_time
cho biết thời điểm xảy ra thay đổi gần đây nhất đối với tài nguyên. Do đó,
độ mới của dữ liệu được lưu vào bộ nhớ đệm cục bộ có thể được so sánh với giá trị của trường này để giúp
xác định xem dữ liệu cục bộ có lỗi thời hay không.
Xin lưu ý rằng trường này cũng có thể lọc, nghĩa là trường này có thể được sử dụng trong WHERE
mệnh đề của truy vấn Ngôn ngữ truy vấn Google Ads (GAQL), cho phép bạn truy vấn
những thay đổi về tài nguyên đã xảy ra trước hoặc sau một thời gian nhất định.
Ví dụ: tìm tất cả các thay đổi đã diễn ra cho một loại tài nguyên nhất định trong tuần trước có thể được thực hiện bằng thuộc tính GAQL sau mệnh đề:
WHERE change_status.last_change_date_time DURING LAST_7_DAYS