更改状态

ChangeStatus 提供了一种跟踪特定时间段内账号中哪些资源发生了更改的方法。如果资源在您指定的时间段内发生了多次更改，则系统只会返回最近一次更改。然后，您可以确定是否需要将本地数据库值与该时间段内发生更改的值同步。

例如，如果您在指定的时间段内添加了某个广告系列，然后又更新了该广告系列，则系统只会返回 UPDATE 操作的更改状态，而不会返回 ADD 操作的更改状态。如果您将时间范围的结束时间移到更新之前，则会看到 ADD 操作。

如果您想要查看包含详细视图的完整字段级结果，请参阅 ChangeEvent。

了解报告的更改的范围

当 ChangeStatus 指示对资源（例如 CAMPAIGN）进行了更改时，这意味着资源本身或其下属资源（该广告系列中的广告组、广告或条件）已发生修改。

ChangeStatus 资源旨在提供账号中哪些部分有活动的概览。如果子资源发生更改，系统可能会返回父资源的 ID，以确保不会遗漏任何修改。对于未在 ChangeStatusResourceType 枚举中明确列出的资源类型，这一点尤其适用。

例如，虽然对广告组出价调节系数的修改会标记 AdGroupBidModifier资源类型，但对粒度较低或较新的子实体的更改可能会标记父级 Campaign或AdGroup 。

如需获取有关具体更改内容的字段级详细信息，您可以使用 ChangeEvent资源，该资源可提供更详细视图，了解创建和更新。

Change Status 类型

系统会跟踪以下资源类型。请注意，资源类型 ID 与枚举值索引不同ChangeStatusResourceType。

资源类型	值	资源类型 ID
核心实体
Google Ads 广告组	AD_GROUP	2
广告组广告	AD_GROUP_AD	3
广告组出价调节系数	AD_GROUP_BID_MODIFIER	11
广告组条件	AD_GROUP_CRITERION	4
广告组 Feed	AD_GROUP_FEED	12
素材资源组	ASSET_BUNDLE	19
广告系列	CAMPAIGN	5
广告系列预算	CAMPAIGN_BUDGET	7
广告系列条件	CAMPAIGN_CRITERION	6
Feed
广告系列 Feed	CAMPAIGN_FEED	9
动态	FEED	8
Feed 项	FEED_ITEM	10
共享集
共享集	SHARED_SET	17
广告系列共享集	CAMPAIGN_SHARED_SET	18
素材资源
素材资源	ASSET	13
素材资源组	ASSET_SET	25
客户素材资源	CUSTOMER_ASSET	14
广告系列素材资源	CAMPAIGN_ASSET	15
广告系列素材资源集	CAMPAIGN_ASSET_SET	26
广告组素材资源	AD_GROUP_ASSET	16

按 ID 确定资源类型

对于较早的 API 版本，Google Ads API 可以返回 UNKNOWN 资源类型值的行，这意味着该类型在未来的 Google Ads API 版本中受支持，但在当前版本发布时未完全受支持。发生这种情况时，您仍然可以通过解析返回的 resource_name 来确定行的资源类型。

资源名称格式为：

customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}

可能有一个或多个额外的 ID，以 - 字符分隔，但相关 ID 是 resource_type_id，即最后一个斜杠后的第二个 ID。上表列出了所有资源类型 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());
    }
  }
}

C#

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