Статус изменений предоставляет средства для отслеживания того, какие ресурсы изменились в учетной записи за определенный период времени. Если ресурс претерпел несколько изменений в течение заданного периода времени, возвращается только последнее изменение.
Используйте эту службу, чтобы определить, нужно ли синхронизировать локальные значения в вашей базе данных со значениями, которые изменились за указанный период времени.
Например, если в течение определенного периода времени вы добавляете, а затем обновляете данную кампанию, возвращается только статус изменения для операции UPDATE
(не для операции ADD
). Если вы переместите конец таймфрейма до обновления, вы увидите операцию ADD
.
Если вам нужны полные результаты по полям с подробным представлением, аналогичным пользовательскому интерфейсу истории изменений, используйте службу событий изменений .
Изменить типы статусов
Служба изменений в настоящее время отслеживает изменения для следующих типов ресурсов :
Тип ресурса | Стоимость | Идентификатор типа ресурса |
---|---|---|
Основные сущности | ||
Группа объявлений | ГРУППА_ОБЪЯВЛЕНИЙ | 2 |
Объявление группы объявлений | AD_GROUP_AD | 3 |
Модификатор ставок для группы объявлений | AD_GROUP_BID_MODIFIER | 11 |
Критерий группы объявлений | AD_GROUP_CRITERION | 4 |
Фид группы объявлений | AD_GROUP_FEED | 12 |
Кампания | КАМПАНИЯ | 5 |
Критерий кампании | КАМПАНИЯ_CRITERION | 6 |
Фиды | ||
Фид кампании | CAMPAIGN_FEED | 9 |
Подача | ПОДАЧА | 8 |
Элемент фида | FEED_ITEM | 10 |
Общие наборы | ||
Общий набор | SHARED_SET | 17 |
Общий набор кампании | КАМПАНИЯ_SHARED_SET | 18 |
Ресурсы | ||
Актив | АКТИВ | 13 |
Актив клиента | CUSTOMER_ASSET | 14 |
Объект кампании | КАМПАНИЯ_АКТИВ | 15 |
Объект группы объявлений | AD_GROUP_ASSET | 16 |
Отслеживание дополнительных типов ресурсов планируется в будущих выпусках.
Определение типа ресурса по ID
Google Ads API может возвращать строки со значением UNKNOWN
типа ресурса для более старых версий API. Это означает, что этот тип поддерживается в будущей версии Google Ads API, но не полностью поддерживался на момент выпуска вашей текущей версии.
В этом случае вы все равно можете определить тип ресурса строки, проанализировав возвращенное resource_name
.
Формат имени ресурса:
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
Может быть один или несколько дополнительных идентификаторов, разделенных символом -
, но здесь уместно указать resource_type_id
, второй идентификатор после последней косой черты. Полный список идентификаторов типов ресурсов см. в таблице выше.
Получение изменений
Список изменений можно фильтровать по дате, а также по типу ресурса. Операция над данным ресурсом будет одной из следующих: ADDED
, CHANGED
или REMOVED
.
Вы можете получить список всех изменений для всех типов ресурсов. Возвращенный resource_type
— это измененное поле. Все родительские поля также заполняются. Например, если изменился критерий ad_group_criterion
, поле ad_group
также будет заполнено.
Запрос должен фильтроваться по дате за последние 90 дней (и, возможно, по времени) и должен включать предложение LIMIT
, установленное не более чем на 10 000 результатов.
Ява
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()); } } }
С#
public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V12.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; }
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 by specifying page size. $response = $googleAdsServiceClient->search($customerId, $query, ['pageSize' => 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; }
питон
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 if resource_type == "AD_GROUP_AD": resource_name = cs.ad_group_ad if resource_type == "AD_GROUP_CRITERION": resource_name = cs.ad_group_criterion if resource_type == "CAMPAIGN": resource_name = cs.campaign if 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, 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
Перл
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::V12::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
, чтобы указать, когда произошло самое последнее изменение любого данного ресурса. Таким образом, свежесть локально кэшированных данных можно сравнить со значением этого поля, чтобы определить, устарели ли локальные данные.
Обратите внимание, что это поле также можно фильтровать , то есть его можно использовать в WHERE
запроса Google Ads Query Language (GAQL). Это позволяет запрашивать изменения в ресурсах, которые произошли до или после заданного времени.
Например, найти все изменения, которые произошли для определенного типа ресурса за последнюю неделю, можно с помощью предиката GAQL, например:
... WHERE change_status.last_change_date_time DURING LAST_7_DAYS