Thay đổi trạng thái

Video: Trạng thái

Thay đổi trạng thái cung cấp một phương thức để theo dõi tài nguyên nào đã thay đổi trong tài khoản trong một khoảng thời gian nhất định. Nếu một tài nguyên có nhiều thay đổi trong khoảng thời gian nhất định, thì chỉ thay đổi mới nhất được trả về. Sau đó, bạn có thể xác định xem mình có cần đồng bộ hoá các giá trị cơ sở dữ liệu cục bộ với các giá trị đã thay đổi trong khoảng thời gian hay không.

Ví dụ: nếu trong một khoảng thời gian nhất định bạn thêm rồi cập nhật một chiến dịch nhất định, thì hệ thống sẽ chỉ trả về trạng thái thay đổi cho UPDATE chứ không phải cho thao tác ADD. Nếu di chuyển điểm kết thúc của khung thời gian đến trước thời điểm cập nhật, thì bạn sẽ thấy thao tác ADD.

Nếu bạn muốn có kết quả hoàn chỉnh theo từng trường ở chế độ xem chi tiết tương tự như trang web Nhật ký thay đổi, hãy xem phần Sự kiện thay đổi.

Thay đổi loại trạng thái

Các loại tài nguyên sau đây được theo dõi. Xin lưu ý rằng mã nhận dạng loại tài nguyên khác với các chỉ mục giá trị enum của ChangeStatusResourceType.

Loại tài nguyên Giá trị Mã loại tài nguyên
Các thực thể chính
Nhóm quảng cáo AD_GROUP 2
Loại quảng cáo của nhóm quảng cáo AD_GROUP_AD 3
Hệ số sửa đổi giá thầu cho nhóm quảng cáo AD_GROUP_BID_MODIFIER 11
Tiêu chí nhóm quảng cáo AD_GROUP_CRITERION 4
Nguồn cấp dữ liệu của nhóm quảng cáo AD_GROUP_FEED 12
Chiến dịch CHIẾN DỊCH 5
Tiêu chí chiến dịch CAMPAIGN_CRITERION 6
Nguồn cấp dữ liệu
Nguồn cấp dữ liệu của chiến dịch CAMPAIGN_FEED 9
Nguồn cấp dữ liệu NGUỒN CẤP DỮ LIỆU 8
Mục nguồn cấp dữ liệu FEED_ITEM 10
Nhóm chia sẻ
Nhóm chia sẻ SHARED_SET 17
Nhóm chia sẻ chiến dịch CAMPAIGN_SHARED_SET 18
Tài sản
Tài sản TÀI SẢN 13
Thành phần của khách hàng CUSTOMER_ASSET 14
Thành phần của chiến dịch CAMPAIGN_ASSET 15
Thành phần nhóm quảng cáo AD_GROUP_ASSET 16

Xác định loại tài nguyên theo mã nhận dạng

API Google Ads có thể trả về các hàng có giá trị loại tài nguyên UNKNOWN cho các phiên bản API cũ hơn, nghĩa là loại này được hỗ trợ trong phiên bản sau này của API Google Ads, nhưng không được hỗ trợ đầy đủ tại thời điểm phát hành phiên bản hiện tại. Khi điều này xảy ra, bạn vẫn có thể xác định loại tài nguyên của hàng bằng cách phân tích cú pháp resource_name được trả về.

Định dạng tên tài nguyên là:

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

Có thể có một hoặc nhiều mã nhận dạng bổ sung, được phân tách bằng ký tự -, nhưng mã phù hợp là resource_type_id — mã nhận dạng thứ hai sau dấu gạch chéo kết thúc. Bảng trước liệt kê tất cả mã nhận dạng loại tài nguyên.

Truy xuất các thay đổi

Bạn có thể lọc danh sách các thay đổi theo ngày cũng như theo loại tài nguyên. Thao tác trên một tài nguyên nhất định là một trong các thao tác sau: ADDED, CHANGED hoặc REMOVED.

Bạn có thể truy xuất danh sách tất cả các thay đổi đối với mọi loại tài nguyên. resource_type được trả về là trường đã thay đổi. Hệ thống cũng điền sẵn mọi trường gốc. Ví dụ: nếu ad_group_criterion thay đổi, thì trường ad_group cũng sẽ được điền.

Nội dung thay đổi có thể mất tới 3 phút mới được phản ánh trong kết quả trạng thái thay đổi.

Truy vấn phải lọc theo ngày trong vòng 90 ngày qua và không bắt buộc phải là thời gian, đồng thời phải bao gồm mệnh đề LIMIT được đặt thành tối đa 10.000 kết quả.

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

C#

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

1.199

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(
        SearchGoogleAdsRequest::build($customerId, $query)->setPageSize(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;
}
      

Python

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
        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 = 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,
    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
      

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::V16::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 "";
  }
}
      

Đồng bộ hoá trên thiết bị

Sau khi truy xuất resource_name chính xác, bạn phải thực hiện truy vấn mới có tên tài nguyên này để lấy tất cả các giá trị hiện tại của tài nguyên. Hệ thống không theo dõi trạng thái thay đổi đối với các giá trị đã thay đổi của một tài nguyên cụ thể mà chỉ những tài nguyên đã thay đổi. Chương trình gọi sẽ chịu trách nhiệm xác định sự khác biệt giữa giá trị trước đó và giá trị hiện tại.

Thay đổi thời gian

Trường last_change_date_time cho biết thời điểm xảy ra thay đổi gần đây nhất đối với một tài nguyên. Do đó, bạn có thể so sánh độ mới của dữ liệu được lưu vào bộ nhớ đệm cục bộ với giá trị của trường này để xác định xem dữ liệu cục bộ đã lỗi thời hay chưa.

Xin lưu ý rằng trường này cũng có thể lọc, nghĩa là bạn có thể sử dụng trường này trong mệnh đề WHERE của truy vấn Ngôn ngữ truy vấn Google Ads (GAQL), cho phép bạn truy vấn những thay đổi về tài nguyên đã xảy ra trước hoặc sau một thời gian nhất định.

Ví dụ: bạn có thể thực hiện việc tìm tất cả các thay đổi đã xảy ra cho một loại tài nguyên nhất định trong tuần trước bằng mệnh đề thuộc tính GAQL sau đây:

WHERE change_status.last_change_date_time DURING LAST_7_DAYS