Stan zmian umożliwia śledzenie, które zasoby uległy zmianie na koncie w określonym czasie. Jeśli zasób uległ zmianie kilka razy w określonym przedziale czasu, zwrócona zostanie tylko najnowsza zmiana. Następnie możesz określić, czy musisz zsynchronizować wartości lokalnej bazy danych z wartościami, które uległy zmianie w danym okresie.
Jeśli na przykład w danym okresie dodasz daną kampanię, a potem ją zaktualizujesz, zwrócony zostanie tylko stan zmiany operacji UPDATE
, a nie ADD
. Jeśli przesuniesz koniec przedziału czasowego przed aktualizacją, zobaczysz operację ADD
.
Jeśli chcesz wyświetlić pełne wyniki w każdym polu z wyświetlaniem szczegółowym podobnym do strony internetowej Historii zmian, zapoznaj się z artykułem Zdarzenie zmiany.
Zmiana typów stanu
Śledzenie obejmuje te typy zasobów: Pamiętaj, że identyfikatory typów zasobów różnią się od indeksów wartości typu enumeracji w ChangeStatusResourceType
.
Typ zasobu | Wartość | Identyfikator typu zasobu |
---|---|---|
Podstawowe elementy | ||
Grupa reklam | AD_GROUP | 2 |
Reklama z grupy reklam | AD_GROUP_AD | 3 |
Modyfikator stawki grupy reklam | AD_GROUP_BID_MODIFIER | 11 |
Kryterium w grupie reklam | AD_GROUP_CRITERION | 4 |
Kanał grupy reklam | AD_GROUP_FEED | 12 |
Grupa plików | ASSET_BUNDLE | 19 |
Kampania | KAMPANIA | 5 |
Kryterium kampanii | CAMPAIGN_CRITERION | 6 |
Pliki danych | ||
Kanał kampanii | CAMPAIGN_FEED | 9 |
Kanał | AKTYWNOŚĆ | 8 |
Element kanału | FEED_ITEM | 10 |
Udostępnione zestawy | ||
Wspólny zestaw | SHARED_SET | 17 |
Wspólny zestaw kampanii | CAMPAIGN_SHARED_SET | 18 |
Assets | ||
Komponent | ZASÓB | 13 |
Zasób klienta | CUSTOMER_ASSET | 14 |
Komponent kampanii | CAMPAIGN_ASSET | 15 |
Komponent grupy reklam | AD_GROUP_ASSET | 16 |
Określanie typu zasobu na podstawie identyfikatora
Interfejs Google Ads API może zwracać wiersze z wartością typu zasobu UNKNOWN
w przypadku wcześniejszych wersji interfejsu API, co oznacza, że typ jest obsługiwany w przyszłej wersji interfejsu Google Ads API, ale nie był w pełni obsługiwany w momencie wydania bieżącej wersji. W takiej sytuacji nadal możesz określić typ zasobu wiersza, analizując zwrócony parametr resource_name
.
Format nazwy zasobu:
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
Może być więcej dodatkowych identyfikatorów rozdzielonych znakiem -
, ale istotny jest ten oznaczony jako resource_type_id
– drugi identyfikator po ostatnim ukośniku. Poprzednia tabela zawiera wszystkie identyfikatory typów zasobów.
Pobieranie zmian
Listę zmian możesz filtrować według daty i typu zasobu. Operacja dotycząca danego zasobu może być jedną z tych operacji: ADDED
, CHANGED
lub REMOVED
.
Możesz pobrać listę wszystkich zmian dla wszystkich typów zasobów. Zwrócone pole resource_type
to pole, które uległo zmianie. Wypełniane są też wszystkie pola nadrzędne. Jeśli na przykład zmieni się wartość pola ad_group_criterion
, pole ad_group
zostanie również wypełnione.
Odzwierciedlenie zmiany w wynikach stanu zmiany może potrwać do 3 minut.
Zapytanie musi zawierać filtrowanie według daty z ostatnich 90 dni i opcjonalnie według czasu. Musi też zawierać klauzulę LIMIT
z maksymalnie 10 tys. wyników.
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()); } } }
public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V19.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; }
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; }
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}" )
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
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::V19::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 ""; } }
Synchronizacja lokalna
Po pobraniu dokładnego zasobu resource_name
należy przesłać nowe zapytanie z tą nazwą zasobu, aby uzyskać wszystkie jego bieżące wartości. Stan zmian nie jest śledzony w przypadku zmienionych wartości konkretnego zasobu – śledzone są tylko które zasoby się zmieniły. Określanie różnicy między poprzednimi a bieżącymi wartościami należy do programu wywołującego.
Zmień godzinę
Pole last_change_date_time
wskazuje, kiedy zasób został ostatnio zmieniony. Dzięki temu można porównać aktualność danych w lokalnej pamięci podręcznej z wartością tego pola, aby określić, czy dane lokalne są nieaktualne.
Pamiętaj, że to pole można też filtrować, co oznacza, że można go używać w klauzuli WHERE
zapytania w języku Google Ads Query Language (GAQL), aby wyszukiwać zmiany w zasobach, które nastąpiły przed lub po określonym czasie.
Na przykład za pomocą tego zapytania GAQL możesz znaleźć wszystkie zmiany, które wystąpiły w przypadku określonego typu zasobu w ostatnim tygodniu:
WHERE change_status.last_change_date_time DURING LAST_7_DAYS