Thay đổi trạng thái cung cấp một phương tiện để theo dõi những tài nguyên nào đã thay đổi trong một tài khoản trong một khoảng thời gian nhất định. Nếu 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ề.
Sử dụng dịch vụ này để xác định xem bạn có cần đồng bộ hoá các giá trị cục bộ trong cơ sở dữ liệu với các giá trị đã thay đổi trong khoảng thời gian nhất định đó hay không.
Ví dụ: nếu trong một khoảng thời gian nhất định, bạn thêm và cập nhật một chiến dịch nhất định, thì chỉ trạng thái thay đổi của thao tác UPDATE (không phải đối với ADD) mới được trả về. Nếu di chuyển cuối khung thời gian này trước khi cập nhật, bạn sẽ thấy hoạt động ADD.
Nếu bạn muốn kết quả hoàn chỉnh theo từng trường có chế độ xem chi tiết tương tự như giao diện người dùng Nhật ký thay đổi, hãy sử dụng dịch vụ Thay đổi sự kiện.
Thay đổi loại Trạng thái
Dịch vụ thay đổi hiện theo dõi các thay đổi đối với các loại tài nguyên sau:
| Loại tài nguyên | Giá trị | Mã loại tài nguyên |
|---|---|---|
| Các thực thể cốt lõi | ||
| Nhóm quảng cáo | NHÓM_DỊCH_VỤ | 2 |
| Loại quảng cáo của nhóm quảng cáo | QUẢNG CÁO_GROUP_AD | 3 |
| Hệ số sửa đổi giá thầu cho nhóm quảng cáo | QUẢNG CÁO_GROUP_BID_LENGTHINMONTHS | 11 |
| Tiêu chí nhóm quảng cáo | TRẠNG_THÁI_DỊCH_VỤ_QUẢNG_CÁO | 4 |
| Nguồn cấp dữ liệu của nhóm quảng cáo | QUẢNG CÁO_NGUỒN CẤP DỮ LIỆU | 12 |
| Chiến dịch | CHIẾN DỊCH | 5 |
| Tiêu chí chiến dịch | CHIẾN DỊCH | 6 |
| Nguồn cấp dữ liệu | ||
| Nguồn cấp dữ liệu của chiến dịch | CHIẾN DỊCH | 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 | NGUỒN CẤP DỮ LIỆU | 10 |
| Nhóm chia sẻ | ||
| Nhóm chia sẻ | ĐÃ CHIA SẺ_TỔ CHỨC | 17 |
| Nhóm chia sẻ chiến dịch | CHIẾN DỊCH_CHIA SẺ_TỔNG QUAN | 18 |
| Thành phần của mẫu quảng cáo | ||
| Thành phần | THÀNH PHẦN | 13 |
| Thành phần của khách hàng | TÀI SẢN CỦA KHÁCH HÀNG | 14 |
| Thành phần của chiến dịch | CHIẾN DỊCH | 15 |
| Thành phần nhóm quảng cáo | TRẠNG_THÁI_DỊCH_VỤ_QUẢNG_CÁO | 16 |
Chúng tôi dự định theo dõi các loại tài nguyên bổ sung cho các bản phát hành trong tương lai.
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ũ. Điều này có nghĩa là loại dữ liệu này được hỗ trợ trong một 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 phiên bản hiện tại được phát hành.
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 khác, được phân tách bằng ký tự -, nhưng mã liên quan ở đây là resource_type_id, mã nhận dạng thứ hai sau dấu gạch chéo cuối cùng. Hãy xem bảng bên trên để biết danh sách đầy đủ các mã loại tài nguyên.
Đang tải các thay đổi
Bạn có thể lọc danh sách các thay đổi theo ngày cũng như loại tài nguyên. Thao tác trên một tài nguyên nhất định sẽ là một trong các hàm ADDED, CHANGED hoặc REMOVED.
Bạn có thể truy xuất danh sách tất cả thay đổi cho tất cả các loại tài nguyên. resource_type được trả về là trường đã thay đổi. Mọi trường mẹ cũng được điền sẵn. Ví dụ: nếu trường ad_group_criterion thay đổi, trường ad_group cũng sẽ được điền sẵn.
Truy vấn phải lọc ngày trong vòng 90 ngày qua (và có thể chọn thời gian) và phải bao gồm mệnh đề LIMIT được đặt 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.V13.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($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;
}
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
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}"
)
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::V13::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á cục 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. Dịch vụ trạng thái thay đổi không theo dõi các giá trị đã thay đổi của tài nguyên cụ thể mà chỉ theo dõi các tài nguyên đã thay đổi.
Việc xác định sự khác biệt giữa các giá trị trước đó và hiện tại là trách nhiệm của chương trình gọi.
Kiểm tra thời gian thay đổi của một tài nguyên
Dịch vụ này cung cấp 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 nhất định bất kỳ.
Do đó, hệ thống có thể so sánh độ mới của dữ liệu lưu vào bộ nhớ đệm trên máy với giá trị của trường này để giúp xác định xem dữ liệu cục bộ có phải đã cũ hay không.
Xin lưu ý rằng trường này cũng có thể lọc, nghĩa là trường này có thể được dùng trong
mệnh đề WHERE của một truy vấn Ngôn ngữ truy vấn Google Ads (GAQL). Điều này cho phép bạn truy vấn các thay đổi trong 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ể tìm thấy tất cả thay đổi đã xảy ra cho một loại tài nguyên nhất định trong tuần qua với mệnh đề thuộc tính GAQL như:
... WHERE change_status.last_change_date_time DURING LAST_7_DAYS