يوفر تغيير الحالة وسيلة لتتبع الموارد التي تغيرت داخل الحساب خلال فترة زمنية محددة. في حال حذف حدوث تغييرات متعددة في أحد الموارد خلال الفترة الزمنية المحدّدة، عندئذ يتم إرجاع آخر تغيير. يمكنك بعد ذلك تحديد ما إذا كنت بحاجة إلى مزامنة وقيم قاعدة البيانات المحلية بتلك التي تغيرت خلال الفترة الزمنية.
على سبيل المثال، إذا قمت خلال فترة زمنية معينة بإضافة ثم تحديث
للحملة، بل حالة التغيير فقط لـ UPDATE
وليس ADD
يتم إرجاع العملية. إذا غيّرت نهاية الإطار الزمني إلى ما قبل
تحديث، ستظهر لك عملية ADD
.
إذا كنت تريد الحصول على النتائج الكاملة كل حقل على حدة مع عرض تفصيلي مشابه صفحة الويب "سجلّ التغييرات"، يُرجى الاطّلاع على تغيير الحدث.
تغيير أنواع الحالات
المورد التالي
أنواعها هي
ونتبعه. يُرجى العلم أنّ أرقام تعريف أنواع الموارد مختلفة عن قيمة التعداد.
فهارس
ChangeStatusResourceType
نوع المورد | القيمة | رقم تعريف نوع المورد |
---|---|---|
الكيانات الأساسية | ||
المجموعة الإعلانية | AD_GROUP | 2 |
نوع الإعلان للمجموعة الإعلانية | AD_GROUP_AD | 3 |
معدِّل عروض أسعار المجموعات الإعلانية | AD_GROUP_BID_MODIFIER | 11 |
معيار المجموعة الإعلانية | AD_GROUP_CRITERION | 4 |
خلاصة المجموعة الإعلانية | AD_GROUP_FEED | 12 |
مجموعة مواد العرض | ASSET_BUNDLE | 19 |
الحملة | الحملة | 5 |
معيار الحملة | CAMPAIGN_CRITERION | 6 |
الخلاصات | ||
خلاصة الحملة | CAMPAIGN_FEED | 9 |
الخلاصة | الخلاصة | 8 |
عنصر الخلاصة | FEED_ITEM | 10 |
العناصر المشتركة | ||
المجموعة المشتركة | SHARED_SET | 17 |
المجموعة المشتركة للحملة | CAMPAIGN_SHARED_SET | 18 |
Assets | ||
مادة العرض | مادة العرض | 13 |
مادة عرض العميل | CUSTOMER_ASSET | 14 |
مادة عرض الحملة | CAMPAIGN_ASSET | 15 |
مادة عرض المجموعة الإعلانية | AD_GROUP_ASSET | 16 |
تحديد نوع المورد حسب رقم التعريف
يمكن أن تعرض Google Ads API صفوفًا تحتوي على قيمة نوع مورد UNKNOWN
للأغراض السابقة
إصدارات واجهة برمجة التطبيقات، أي أنّ النوع يتوافق مع إصدار مستقبلي من
Google Ads API، ولكن لم يكن متوافقًا بشكل كامل في وقت طرح الإصدار الحالي
صدرت. وعند حدوث ذلك، سيظل بإمكانك تحديد نوع مورد
عن طريق تحليل 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 دقائق حتى يظهر في حالة التغيير نتائجك.
يجب تصفية الاستعلام على تاريخ خلال التسعين يومًا الماضية، واختياريًا وقتًا،
ويجب أن يتضمّن عبارة 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.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.V17.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; }
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 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::V17::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 ""; } }
المزامنة محليًا
بعد تحديد قيمة resource_name
الدقيقة
استردادها، يجب إجراء استعلام جديد باسم المورد هذا للحصول على جميع
القيم الحالية للمورد. عدم تتبع حالة التغيير لنوع معين
القيم المتغيرة للمورد - فقط التي تغيرت الموارد. يعتمد تحديد
يعتبر الفرق بين القيم السابقة والحالية مسؤولية
برنامج الاتصال.
تغيير الوقت
last_change_date_time
إلى وقت حدوث آخر تغيير في أحد الموارد. وبالتالي،
يمكن مقارنة حداثة البيانات المخزنة مؤقتًا محليًا بقيمة هذا الحقل للمساعدة في
لتحديد ما إذا كانت البيانات المحلية قديمة.
تجدر الإشارة إلى أنّ هذا الحقل قابل للفلترة أيضًا، ما يعني أنّه يمكن استخدامه في WHERE
.
واحدة من استعلامات لغة الاستعلام (GAQL) في "إعلانات Google"، تسمح لك بالاستعلام عن
التغيرات في الموارد التي حدثت قبل أو بعد فترة معينة.
على سبيل المثال، العثور على جميع التغييرات التي حدثت لنوع معيّن من الموارد خلال الأسبوع الماضي باستخدام فلتر GAQL التالي :
WHERE change_status.last_change_date_time DURING LAST_7_DAYS