שינוי סטטוס מאפשר לעקוב אחרי המשאבים שהשתנו בחשבון במהלך תקופת זמן נתונה. אם במשאב היו כמה שינויים במהלך תקופת הזמן הנתונה, מוחזר רק השינוי האחרון. לאחר מכן תוכלו לקבוע אם צריך לסנכרן את הערכים של מסד הנתונים המקומי עם ערכים שהשתנו באותה תקופת זמן.
לדוגמה, אם במהלך תקופה נתונה מוסיפים קמפיין נתון ומעדכנים אותו, מוחזר רק סטטוס השינוי של UPDATE
ולא של הפעולה ADD
. אם מעבירים את סוף מסגרת הזמן למצב שלפני העדכון, הפעולה ADD
תופיע.
אם רוצים לקבל את התוצאות המלאות בכל שדה, עם תצוגה מפורטת שדומה לדף האינטרנט של היסטוריית השינויים, ראו אירוע שינויים.
שינוי סוגי הסטטוסים
יש מעקב אחרי סוגי המשאבים הבאים. שימו לב שהמזהים של סוגי המשאבים שונים מאינדקסים של ערכי enum של ChangeStatusResourceType
.
סוג המשאב | ערך | מזהה סוג המשאב |
---|---|---|
ישויות ליבה | ||
קבוצת מודעות | AD_GROUP | 2 |
מודעה בקבוצת מודעות | AD_GROUP_AD | 3 |
מגביל הצעת המחיר של קבוצת מודעות | AD_GROUP_BID_MODIFIER | 11 |
קריטריון קבוצת מודעות | AD_GROUP_CRITERION | 4 |
עדכון קבוצת מודעות | AD_GROUP_FEED | 12 |
עדיפות | קמפיין | 5 |
קריטריון קמפיין | CAMPAIGN_CRITERION | 6 |
פידים | ||
עדכון לקמפיין | CAMPAIGN_FEED | 9 |
פיד | עדכון | 8 |
פריט עדכון | FEED_ITEM | 10 |
קבוצות משותפות | ||
קבוצה משותפת | SHARED_SET | 17 |
קבוצה משותפת בקמפיין | CAMPAIGN_SHARED_SET | 18 |
נכסים | ||
הנכס | נכס | 13 |
נכס דיגיטלי של לקוח | CUSTOMER_ASSET | 14 |
נכס של קמפיין | CAMPAIGN_ASSET | 15 |
נכס דיגיטלי של קבוצת מודעות | AD_GROUP_ASSET | 16 |
קביעת סוג המשאב לפי מזהה
גרסאות API קודמות של Google Ads API יכולות להחזיר שורות עם ערך של סוג משאב UNKNOWN
בגרסאות API קודמות, כלומר הסוג נתמך בגרסה עתידית של 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 דקות לפני שהשינוי יבוא לידי ביטוי בתוצאות של סטטוס השינוי.
השאילתה צריכה לסנן לפי תאריך מ-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.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
של שאילתה בשפת השאילתה של Google Ads (GAQL), וכך להריץ שאילתות על שינויים במשאבים שהתרחשו לפני או אחרי זמן נתון.
לדוגמה, אפשר למצוא את כל השינויים שהתרחשו בסוג משאב מסוים בשבוע האחרון בעזרת הפרדקט הבא של GAQL:
WHERE change_status.last_change_date_time DURING LAST_7_DAYS