تغيير خدمة الحالة

الفيديو: الحالة

توفر حالة التغيير وسيلة لتتبع الموارد التي طرأ عليها تغيير ضمن حساب خلال فترة زمنية معينة. إذا كان المورد قد أجرى تغييرات متعددة خلال الفترة الزمنية المحددة، فسيتم عرض آخر تغيير فقط.

استخدم هذه الخدمة لتحديد ما إذا كنت تحتاج إلى مزامنة القيم المحلية في قاعدة البيانات مع القيم التي تغيرت أثناء تلك الفترة الزمنية.

على سبيل المثال، إذا أضفت خلال فترة زمنية محدّدة حملة ثم حدّثتها، لن يتم عرض سوى حالة التغيير للعملية UPDATE (وليس لعملية ADD). إذا نقلت نهاية الإطار الزمني إلى ما قبل التحديث، فستلاحظ العملية ADD.

إذا كنت تريد الحصول على نتائج حقل تلو الأخرى مع عرض تفصيلي مشابه لواجهة مستخدم سجلّ التغييرات، فاستخدم خدمة حدث التغيير.

ملاحظة مهمة: لن تحتوي جميع الصفوف من حالة التغيير على تفاصيل مقابلة في حدث التغيير. يمكنك الاطّلاع على حدود أحداث التغيير بالكامل للحصول على التفاصيل.

تغيير أنواع الحالة

تتبع خدمة التغيير حاليًا التغييرات التي طرأت على أنواع الموارد التالية:

ملاحظة: تختلف أرقام تعريف أنواع الموارد عن فهارس قيم التعداد في ChangeStatusResourceType. يمكنك الاطّلاع على مزيد من المعلومات عن استخدام هذه الميزة في القسم التالي.

نوع المورد	القيمة	رقم تعريف نوع المورد
الكيانات الأساسية
المجموعة الإعلانية	المجموعة الإعلانية	2
نوع الإعلان للمجموعة الإعلانية	AD_GROUP_AD	3
معدِّل عروض أسعار المجموعات الإعلانية	AD_GROUP_BID_MODIFIER	11
معيار المجموعة الإعلانية	AD_GROUP_CRITERION	4
خلاصة المجموعة الإعلانية	AD_GROUP_FEED	12
الحملة	الحملة	5
معيار الحملة	CAMPAIGN_CRITERION	6
الخلاصات
خلاصة الحملة	خلاصة الحملة	9
الخلاصة	الخلاصة	8
عنصر الخلاصة	الخلاصة	10
المجموعات المشتركة
المجموعة المشتركة	SHARED_SET	17
المجموعة المشتركة للحملة	CAMPAIGN_SHARED_SET	18
مواد العرض
مادة العرض	مادة العرض	13
مادة عرض العميل	مادة عرض العميل	14
مادة عرض الحملة	مادة عرض الحملة	15
مادة عرض المجموعة الإعلانية	AD_GROUP_ASSET	16

يتم التخطيط لتتبع أنواع إضافية من الموارد في الإصدارات المستقبلية.

تحديد نوع المورد حسب رقم التعريف

قد يعرض إعلانات Google API صفوفًا تحتوي على قيمة نوع مورد UNKNOWN لإصدارات واجهة برمجة التطبيقات القديمة. ويعني هذا أن النوع معتمد في الإصدار المستقبلي من إعلانات Google 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 تم تعيينها على 10000 نتيجة على الأكثر.

لغة 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.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;
}
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($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;
}
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
        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}"
        )
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::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 "";
  }
}
get_change_summary.pl
      

الاحتفاظ بالمزامنة محليًا

بعد استرداد resource_name الدقيقة، يجب إجراء طلب بحث جديد باستخدام اسم المورد هذا للحصول على جميع القيم الحالية للمورد. لا تتبع خدمة تغيير الحالة قيم المورد المحددة التي تم تغييرها—فقط الموارد التي تم تغييرها. تحديد مسؤولية الفرق بين القيم السابقة والحالية هو مسؤولية برنامج الاتصال.

التحقق من وقت تغيير المورد

توفّر الخدمة الحقل last_change_date_time للإشارة إلى وقت حدوث آخر تغيير على أي مورد معيّن. وبالتالي، يمكن مقارنة حداثة البيانات المخزنة مؤقتًا محليًا بقيمة هذا الحقل للمساعدة في تحديد ما إذا كانت البيانات المحلية قديمة.

لاحظ أن هذا الحقل قابل للفلترة أيضًا، ما يعني أنه يمكن استخدامه في عبارة WHERE لطلب البحث بلغة "إعلانات Google" (GAQL). يتيح ذلك إمكانية طلب البحث عن التغييرات في الموارد التي تمت قبل أو بعد فترة زمنية محددة.

على سبيل المثال، يمكن العثور على جميع التغييرات التي تم إجراؤها لنوع معيّن من الموارد خلال الأسبوع الماضي باستخدام عبارة إسناد لقيم GAQL مثل:

... WHERE change_status.last_change_date_time DURING LAST_7_DAYS