Изменить статус

Видео : Статус

ChangeStatus позволяет отслеживать изменения ресурсов в учетной записи за определенный период времени. Если ресурс претерпел несколько изменений за указанный период, возвращается только последнее изменение. Затем вы можете определить, нужно ли синхронизировать значения в локальной базе данных с теми, которые изменились за этот период.

Например, если в течение определенного периода времени вы добавляете, а затем обновляете определенную кампанию, возвращается только статус изменения для операции UPDATE , а не для операции ADD . Если вы переместите конец временного интервала на период до обновления, то увидите статус операции ADD .

Если вам нужны полные результаты по каждому полю с подробным представлением, см. ChangeEvent .

Оцените масштабы сообщенных изменений.

Когда ChangeStatus указывает на изменение ресурса, например, CAMPAIGN , это означает, что был изменен либо сам ресурс, либо один из его подчиненных ресурсов — группа объявлений, объявление или критерий в рамках этой кампании.

Ресурс ChangeStatus предназначен для предоставления общего обзора того, какие части вашей учетной записи были затронуты. Если изменение происходит в дочернем ресурсе, может быть возвращен идентификатор родительского ресурса, чтобы гарантировать, что никакие изменения не будут пропущены. Это особенно актуально для типов ресурсов, которые явно не указаны в перечислении ChangeStatusResourceType .

Например, изменение модификатора ставки группы объявлений приводит к изменению типа ресурса AdGroupBidModifier , тогда как изменение менее детализированного или более нового дочернего объекта может привести к изменению родительской Campaign или AdGroup .

Чтобы получить подробную информацию об изменениях на уровне отдельных полей, можно использовать ресурс ChangeEvent , который предоставляет более детальное представление о создании и обновлении данных.

Изменение типов статуса

Отслеживаются следующие типы ресурсов . Обратите внимание, что идентификаторы типов ресурсов отличаются от индексов значений перечисления ChangeStatusResourceType .

Тип ресурса Ценить Идентификатор типа ресурса
Основные сущности
Группа объявлений AD_GROUP 2
Групповое объявление AD_GROUP_AD 3
Модификатор ставок группы объявлений AD_GROUP_BID_MODIFIER 11
Критерий группы объявлений AD_GROUP_CRITERION 4
Лента групп объявлений AD_GROUP_FEED 12
Группа активов ASSET_BUNDE 19
Кампания КАМПАНИЯ 5
Бюджет избирательной кампании Бюджет кампании 7
Критерий кампании КРИТЕРИЙ_КАМПАНИЯ 6
Корма
Лента кампании CAMPAIGN_FEED 9
Кормить КОРМИТЬ 8
Кормовой продукт FEED_ITEM 10
Общие наборы
Общий набор ОБЩИЙ_НАБОР 17
Общий набор кампании CAMPAIGN_SHARED_SET 18
Ресурсы
Объект ОБЪЕКТ 13
Набор активов ASSET_SET 25
Актив клиента АКТИВЫ КЛИЕНТА 14
Материалы кампании CAMPAIGN_ASSET 15
Набор ресурсов кампании CAMPAIGN_ASSET_SET 26
Актив рекламной группы AD_GROUP_ASSET 16

Определите тип ресурса по идентификатору.

В более ранних версиях API Google Ads могут возвращаться строки со значением UNKNOWN resource type, что означает, что этот тип поддерживается в будущих версиях API Google Ads, но не был полностью поддержан на момент выпуска вашей текущей версии. В этом случае вы все равно можете определить тип ресурса строки, проанализировав возвращаемое 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 также заполняется.

Для того чтобы изменения отразились в результатах отслеживания статуса, может потребоваться до 3 минут.

Запрос должен фильтровать результаты по дате за последние 90 дней, а также, при необходимости, по времени, и должен включать условие LIMIT , устанавливающее максимальное количество результатов в 10 000.

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());
    }
  }
}
GetChangeSummary.java

C# 

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V22.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;
}
GetChangeSummary.cs

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;
}
GetChangeSummary.php

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}"
        )
get_change_summary.py

Руби 

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
get_change_summary.rb

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::V22::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 "";
  }
}
get_change_summary.pl

Синхронизация локально

После получения точного resource_name необходимо выполнить новый запрос с этим именем ресурса, чтобы получить все текущие значения ресурса. Статус изменения не отслеживается для конкретных измененных значений ресурса — отслеживается только, какие ресурсы изменились. Определение разницы между предыдущим и текущим значениями является задачей вызывающей программы.

Сменить время

Поле last_change_date_time указывает, когда произошло последнее изменение ресурса. Таким образом, актуальность локально кэшированных данных можно сравнить со значением этого поля, чтобы определить, устарели ли локальные данные.

Обратите внимание, что это поле также можно фильтровать , то есть его можно использовать в условии WHERE запроса Google Ads на языке запросов (GAQL), ​​что позволяет запрашивать изменения в ресурсах, произошедшие до или после заданного времени.

Например, поиск всех изменений, произошедших для определенного типа ресурсов за последнюю неделю, может быть выполнен с помощью следующего предикатного предложения GAQL:

WHERE change_status.last_change_date_time DURING LAST_7_DAYS
Назад
Ссылка на YouTube
Далее
Изменить событие