ChangeStatus menyediakan cara untuk melacak resource mana yang telah berubah dalam akun selama jangka waktu tertentu. Jika resource mengalami beberapa perubahan selama jangka waktu yang Anda tentukan, hanya perubahan terbaru yang akan ditampilkan. Kemudian, Anda dapat menentukan apakah perlu menyinkronkan nilai database lokal dengan nilai yang telah berubah dalam jangka waktu tersebut.
Misalnya, jika selama jangka waktu tertentu Anda menambahkan, lalu memperbarui kampanye tertentu, hanya status perubahan untuk operasi UPDATE yang akan ditampilkan, bukan untuk operasi ADD. Jika Anda memindahkan akhir jangka waktu ke sebelum pembaruan, Anda akan melihat operasi ADD.
Jika Anda menginginkan hasil lengkap kolom demi kolom dengan tampilan mendetail, lihat
ChangeEvent.
Memahami cakupan perubahan yang dilaporkan
Jika ChangeStatus menunjukkan perubahan pada resource, seperti
CAMPAIGN, artinya resource itu sendiri
atau salah satu resource subordinatnya—grup iklan, iklan, atau kriteria dalam
kampanye tersebut—telah diubah.
Resource ChangeStatus bertujuan untuk memberikan ringkasan luas tentang bagian
akun Anda yang telah melihat aktivitas. Jika perubahan terjadi pada resource turunan, ID resource induk mungkin akan ditampilkan untuk memastikan tidak ada modifikasi yang terlewatkan. Hal ini terutama berlaku untuk jenis resource yang tidak tercantum secara eksplisit dalam
enum ChangeStatusResourceType.
Misalnya, meskipun modifikasi pada pengubah bid grup iklan menandai jenis resource
AdGroupBidModifier, perubahan
pada entity turunan yang kurang terperinci atau lebih baru mungkin menandai
Campaign atau AdGroup
induk.
Untuk mendapatkan detail tingkat kolom tentang apa yang sebenarnya berubah, Anda dapat menggunakan resource
ChangeEvent, yang memberikan tampilan yang lebih
mendetail tentang pembuatan dan pembaruan.
Jenis Status Perubahan
Jenis resource berikut dilacak. Perhatikan bahwa ID jenis resource berbeda dengan indeks nilai enum
dari ChangeStatusResourceType.
| Jenis resource | Nilai | ID jenis resource |
|---|---|---|
| Entity Inti | ||
| Grup iklan | AD_GROUP | 2 |
| Iklan grup iklan | AD_GROUP_AD | 3 |
| Pengubah bid grup iklan | AD_GROUP_BID_MODIFIER | 11 |
| Kriteria grup iklan | AD_GROUP_CRITERION | 4 |
| Feed grup iklan | AD_GROUP_FEED | 12 |
| Grup aset | ASSET_BUNDLE | 19 |
| Kampanye | CAMPAIGN | 5 |
| Anggaran kampanye | CAMPAIGN_BUDGET | 7 |
| Kriteria kampanye | CAMPAIGN_CRITERION | 6 |
| Feed | ||
| Feed kampanye | CAMPAIGN_FEED | 9 |
| Feed | FEED | 8 |
| Item feed | FEED_ITEM | 10 |
| Kumpulan Bersama | ||
| Kumpulan bersama | SHARED_SET | 17 |
| Kumpulan bersama kampanye | CAMPAIGN_SHARED_SET | 18 |
| Aset | ||
| Aset | ASSET | 13 |
| Kumpulan Aset | ASSET_SET | 25 |
| Aset pelanggan | CUSTOMER_ASSET | 14 |
| Aset kampanye | CAMPAIGN_ASSET | 15 |
| Kumpulan aset kampanye | CAMPAIGN_ASSET_SET | 26 |
| Aset grup iklan | AD_GROUP_ASSET | 16 |
Menentukan jenis resource berdasarkan ID
Google Ads API dapat menampilkan baris dengan nilai jenis resource UNKNOWN untuk versi API sebelumnya, yang berarti jenis tersebut didukung dalam versi Google Ads API mendatang, tetapi tidak sepenuhnya didukung pada saat versi Anda saat ini dirilis. Jika hal ini terjadi, Anda masih dapat menentukan jenis resource baris dengan mengurai resource_name yang ditampilkan.
Format nama resource adalah:
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
Mungkin ada satu atau beberapa ID tambahan, yang dipisahkan oleh karakter -, tetapi yang relevan adalah resource_type_id—ID kedua setelah garis miring terakhir. Tabel sebelumnya mencantumkan semua ID jenis resource.
Mengambil perubahan
Daftar perubahan dapat difilter menurut tanggal dan jenis resource. Operasi pada resource tertentu adalah salah satu dari
ADDED, CHANGED, atau REMOVED.
Anda dapat mengambil daftar semua perubahan untuk semua jenis resource. yang ditampilkan adalah kolom yang berubah.resource_type Kolom induk juga diisi. Misalnya, jika ad_group_criterion berubah, kolom
ad_group juga akan diisi.
Perubahan dapat memerlukan waktu hingga 3 menit untuk ditampilkan dalam hasil status perubahan.
Kueri harus memfilter tanggal dalam 90 hari terakhir, dan secara opsional waktu, serta harus menyertakan klausa LIMIT yang ditetapkan ke maksimal 10.000 hasil.
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.campaign, " + "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"; 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.V24.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: GoogleAdsClient, customer_id: str) -> None: ads_service: GoogleAdsServiceClient = 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: SearchGoogleAdsRequest = client.get_type( "SearchGoogleAdsRequest" ) search_request.customer_id = customer_id search_request.query = query response: SearchPagedResponse = ads_service.search(request=search_request) row: GoogleAdsRow for row in response: cs: ChangeStatus = row.change_status resource_type: str = cs.resource_type.name resource_name: str 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: str = 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, ) # 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::V25::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 ""; } }
curl
Menyinkronkan secara lokal
Setelah resource_name yang tepat diambil, kueri baru dengan nama resource ini harus dibuat untuk mendapatkan semua nilai resource saat ini. Status perubahan tidak dilacak untuk nilai resource tertentu yang diubah—hanya resource mana yang telah berubah. Menentukan perbedaan antara nilai sebelumnya dan saat ini adalah tanggung jawab program panggilan.
Ubah waktu
Kolom last_change_date_time
menunjukkan kapan perubahan terbaru pada resource terjadi. Dengan demikian, kesegaran data yang di-cache secara lokal dapat dibandingkan dengan nilai kolom ini untuk membantu menentukan apakah data lokal sudah tidak berlaku.
Perhatikan bahwa kolom ini juga dapat difilter, yang berarti dapat digunakan dalam WHERE
klausa kueri Bahasa Kueri Google Ads (GAQL), sehingga Anda dapat membuat kueri untuk
perubahan pada resource yang terjadi sebelum atau setelah waktu tertentu.
Misalnya, menemukan semua perubahan yang terjadi untuk jenis resource tertentu dalam seminggu terakhir dapat dilakukan dengan klausa predikat GAQL berikut:
WHERE change_status.last_change_date_time DURING LAST_7_DAYS