O Change Status (Status da mudança) é uma forma de acompanhar quais recursos mudaram em uma conta durante um determinado período. Se um recurso tiver várias mudanças durante o período especificado, somente a mais recente será retornada. Em seguida, determine se é necessário sincronizar os valores do banco de dados local com aqueles que mudaram no período.
Por exemplo, se durante um determinado período você adicionar e atualizar uma campanha, apenas o status de mudança da operação UPDATE
será retornado, e não o da operação ADD
. Se você mover o fim do período para antes da atualização, verá a operação ADD
.
Se você quiser os resultados completos campo a campo com uma visualização detalhada semelhante à página da web do histórico de mudanças, consulte Evento de mudança.
Mudar tipos de status
Os seguintes tipos de recursos são rastreados. Os IDs de tipo de recurso são diferentes dos índices de valor de enumeração de ChangeStatusResourceType
.
Tipo de recurso | Valor | ID do tipo de recurso |
---|---|---|
Entidades principais | ||
Grupo de anúncios | AD_GROUP | 2 |
Anúncio do grupo de anúncios | AD_GROUP_AD | 3 |
Modificador do lance de grupo de anúncios | AD_GROUP_BID_MODIFIER | 11 |
Critério do grupo de anúncios | AD_GROUP_CRITERION | 4 |
Feed do grupo de anúncios | AD_GROUP_FEED | 12 |
Grupo de recursos | ASSET_BUNDLE | 19 |
Campanha | CAMPANHA | 5 |
Orçamento da campanha | CAMPAIGN_BUDGET | 7 |
Critério da campanha | CAMPAIGN_CRITERION | 6 |
Feeds | ||
Feed de campanha | CAMPAIGN_FEED | 9 |
Feed | FEED | 8 |
Item do feed | FEED_ITEM | 10 |
Conjuntos compartilhados | ||
Conjunto compartilhado | SHARED_SET | 17 |
Conjunto de campanhas compartilhado | CAMPAIGN_SHARED_SET | 18 |
Recursos | ||
Recurso | RECURSO | 13 |
Grupo de recursos | ASSET_SET | 25 |
Recurso do cliente | CUSTOMER_ASSET | 14 |
Recurso da campanha | CAMPAIGN_ASSET | 15 |
Grupo de recursos de campanha | CAMPAIGN_ASSET_SET | 26 |
Recurso do grupo de anúncios | AD_GROUP_ASSET | 16 |
Como determinar o tipo de recurso por ID
A API Google Ads pode retornar linhas com um valor de tipo de recurso UNKNOWN
para versões anteriores da API. Isso significa que o tipo será compatível com uma versão futura da API Google Ads, mas não era totalmente compatível quando sua versão atual foi lançada. Quando isso acontece, ainda é possível determinar o tipo de recurso da linha analisando o resource_name
retornado.
O formato do nome do recurso é:
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
Pode haver um ou mais IDs adicionais, separados pelo caractere -
, mas o relevante é o resource_type_id
, o segundo ID após a barra final. A tabela anterior lista todos os IDs de tipo de recurso.
Recuperar mudanças
A lista de mudanças pode ser filtrada por data e tipo de recurso. A
operação em um determinado recurso é uma das
ADDED
,
CHANGED
ou
REMOVED
.
É possível recuperar a lista de todas as mudanças para todos os tipos de recursos. O resource_type
retornado é o campo que mudou. Todos os campos principais também são preenchidos. Por exemplo, se o
ad_group_criterion
mudar,
o campo ad_group
também será
preenchido.
Uma mudança pode levar até 3 minutos para ser refletida nos resultados do status da mudança.
A consulta precisa filtrar uma data nos últimos 90 dias e, opcionalmente, uma hora. Além disso,ela precisa incluir uma cláusula LIMIT
definida para no máximo 10.000 resultados.
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.V20.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::V20::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 ""; } }
Sincronizar localmente
Depois que o resource_name
exato for
recuperado, uma nova consulta com esse nome de recurso deverá ser feita para obter todos os
valores atuais do recurso. O status de mudança não é rastreado para os valores alterados de um recurso específico, apenas quais recursos foram alterados. Determinar a diferença entre os valores anteriores e atuais é responsabilidade do programa de chamada.
Alterar horário
O campo last_change_date_time
indica quando ocorreu a mudança mais recente em um recurso. Assim, a
atualidade dos dados armazenados em cache localmente pode ser comparada com o valor desse campo para ajudar a
determinar se os dados locais estão desatualizados.
Esse campo também pode ser filtrado, ou seja, usado na cláusula WHERE
de uma consulta da linguagem de consulta do Google Ads (GAQL). Assim, você pode consultar mudanças em recursos que ocorreram antes ou depois de um determinado horário.
Por exemplo, para encontrar todas as mudanças que ocorreram em um determinado tipo de recurso na última semana, use a seguinte cláusula de predicado da GAQL:
WHERE change_status.last_change_date_time DURING LAST_7_DAYS