שינוי סטטוס

סרטון: סטטוס

Change Status (סטטוס השינוי) מאפשר לעקוב אחרי המשאבים שהשתנו בחשבון במהלך תקופת זמן נתונה. אם במשאב היו שינויים מרובים במהלך תקופת הזמן הנתונה, רק השינוי האחרון יוחזר. לאחר מכן אפשר להחליט אם צריך לסנכרן את הערכים של מסד הנתונים המקומי עם אלו שהשתנו בתקופת הזמן.

לדוגמה, אם במהלך תקופת זמן נתונה מוסיפים ואז מעדכנים קמפיין מסוים, מוחזר רק סטטוס השינוי של UPDATE ולא של הפעולה ADD. אם מעבירים את סוף פרק הזמן לפני העדכון, הפעולה ADD תופיע.

כדי לקבל את התוצאות המלאות בכל שדה עם תצוגה מפורטת שדומה לדף האינטרנט של Change History ראו את המאמר Change Event.

נקודת מפתח: לא לכל השורות בסטטוס השינוי יש פרטים תואמים באירוע השינוי. לפרטים נוספים, אפשר לעיין במאמר שינוי הגבלות על אירועים.

שינוי סוגי הסטטוסים

המעקב אחרי סוגי המשאבים הבאים מתבצע. שימו לב שמזהים של סוגי משאבים שונים מהאינדקסים של ערכי טיפוסים בני מנייה (enum) של ChangeStatusResourceType.

סוג משאב	Value	מזהה סוג המשאב
ישויות ליבה
קבוצת מודעות	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

קביעת סוג המשאב לפי מזהה

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

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;
}
GetChangeSummary.cs
      

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 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;
}
GetChangeSummary.php
      

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}"
        )
get_change_summary.py
      

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
get_change_summary.rb
      

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 "";
  }
}
get_change_summary.pl
      

סנכרון מקומי

אחרי שמאחזרים את הערך המדויק resource_name, צריך לשלוח שאילתה חדשה עם שם המשאב הזה כדי לקבל את כל הערכים הנוכחיים של המשאב. לא מתבצע מעקב אחר הסטטוס של ערכים שהשתנו במשאב מסוים, אלא רק אילו משאבים השתנו. תוכנית הקריאות קובעת מה ההבדל בין הערך הקודם לערך הנוכחי.

בשעה אחרת

השדה last_change_date_time מציין מתי התרחש השינוי האחרון במשאב. כך, אפשר להשוות את עדכניות הנתונים שנשמרו במטמון המקומי לערך בשדה הזה כדי לקבוע אם הנתונים המקומיים הם לא עדכניים.

שימו לב שהשדה הזה ניתן לסינון, כלומר אפשר להשתמש בו במשפט WHERE בשאילתה בשפת שאילתות של Google Ads (GAQL), כדי לחפש שינויים במשאבים שהתרחשו לפני או אחרי פרק זמן מסוים.

לדוגמה, כדי לאתר את כל השינויים שהתרחשו בסוג משאב מסוים בשבוע האחרון אפשר למצוא את כל השינויים שהתרחשו בשבוע האחרון באמצעות המשפט המוקדם הבא של GAQL:

WHERE change_status.last_change_date_time DURING LAST_7_DAYS