Google Ads API is returning to beta status. Please read our blog post for more details.

Change Status 服务

Change Status 提供了一种跟踪特定时间段内帐号更改情况(例如广告系列和广告更改)的方法。这可用于多种目的,例如与本地副本保持同步、进行简单的审计或确保自动化流程按预期执行。

Change Status 类型

Change Service 目前会跟踪以下 resource types 的更改情况:

资源类型
广告组 AD_GROUP
广告组广告 AD_GROUP_AD
广告组条件 AD_GROUP_CRITERION
广告系列 CAMPAIGN
广告系列条件 CAMPAIGN_CRITERION

未来,我们将支持跟踪更多资源类型。

获得更改

您可以按日期和资源类型过滤更改列表。给定资源上执行的操作将是 ADDEDCHANGEDREMOVED 中的一项。

可以检索所有资源类型的所有更改的列表。返回的 resource_type 是已发生更改的字段。此外,系统还会填充所有父级字段。例如,如果 ad_group_criterion 发生更改,则系统也会填充父级的 ad_group 字段。

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  String 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_7_DAYS "
          + "ORDER BY change_status.last_change_date_time";

  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().getValue(),
          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.V1.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_7_DAYS " +
        "ORDER BY change_status.last_change_date_time";

    // 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}");
    }
}

/// <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>
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, $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all change statuses.
    $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_7_DAYS '
       . 'ORDER BY change_status.last_change_date_time';

    // 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()->getLastChangeDateTimeValue(),
            $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->getAdGroupValue();
            break;
        case ChangeStatusResourceType::AD_GROUP_AD:
            $resourceName = $changeStatus->getAdGroupAdValue();
            break;
        case ChangeStatusResourceType::AD_GROUP_CRITERION:
            $resourceName = $changeStatus->getAdGroupCriterionValue();
            break;
        case ChangeStatusResourceType::CAMPAIGN:
            $resourceName = $changeStatus->getCampaignValue();
            break;
        case ChangeStatusResourceType::CAMPAIGN_CRITERION:
            $resourceName = $changeStatus->getCampaignCriterionValue();
            break;
    }

    return $resourceName;
}

Python

def resource_name_for_resource_type(resource_type, row):
  """Return the resource name for the resource type.

  Each returned row contains all possible changed fields. This function
  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.

  Args:
    resource_type: the string equivalent of the resource type
    row: a single row returned from the service

  Returns:
    The resource name of the field that changed.
  """
  resource_name = ''  # default for UNSPECIFIED or UNKNOWN
  if resource_type == 'AD_GROUP':
    resource_name = row.change_status.ad_group.value
  elif resource_type == 'AD_GROUP_AD':
    resource_name = row.change_status.ad_group_ad.value
  elif resource_type == 'AD_GROUP_CRITERION':
    resource_name = row.change_status.ad_group_criterion.value
  elif resource_type == 'CAMPAIGN':
    resource_name = row.change_status.campaign.value
  elif resource_type == 'CAMPAIGN_CRITERION':
    resource_name = row.change_status.campaign_criterion.value
  return resource_name

在本地保持同步

检索到精确的 resource_name 后,应该使用此资源名称创建一个新查询,以获取资源的所有当前值。Change Status 服务不会跟踪特定资源的哪些值发生了更改,而只会跟踪哪些资源发生了更改。至于先前值和当前值之间的差异,均由调用程序负责确定。