تغيير الحالة

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

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

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

إذا كنت تريد الحصول على النتائج الكاملة على مستوى الحقل مع عرض تفصيلي، يُرجى الاطّلاع على ChangeEvent.

فهم نطاق التغييرات المُبلَغ عنها

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

يهدف مرجع ChangeStatus إلى تقديم نظرة عامة واسعة النطاق على أجزاء حسابك التي شهدت نشاطًا. إذا حدث تغيير في مرجع ثانوي، قد يتم عرض رقم تعريف المرجع الرئيسي لضمان عدم تفويت أي تعديلات. ينطبق ذلك بشكل خاص على أنواع المَراجع غير المدرَجة بشكل صريح في الـ ChangeStatusResourceType تعداد.

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

للحصول على تفاصيل على مستوى الحقل حول ما تم تغييره بالضبط، يمكنك استخدام الـ ChangeEvent الذي يقدّم عرضًا أكثر تفصيلاً لعمليات الإنشاء والتعديل.

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

يتم تتبُّع أنواع المَراجع التالية. يُرجى العِلم أنّ أرقام تعريف نوع المرجع تختلف عن فهارس قيم التعداد ChangeStatusResourceType.

نوع المرجع القيمة رقم تعريف نوع المرجع
الكيانات الأساسية
المجموعة الإعلانية AD_GROUP 2
نوع الإعلان للمجموعة الإعلانية AD_GROUP_AD 3
تعديل عروض أسعار المجموعات الإعلانية AD_GROUP_BID_MODIFIER 11
معيار المجموعة الإعلانية AD_GROUP_CRITERION 4
خلاصة المجموعة الإعلانية AD_GROUP_FEED 12
مجموعة مواد العرض ASSET_BUNDLE 19
الحملة CAMPAIGN 5
ميزانية الحملة CAMPAIGN_BUDGET 7
معيار الحملة CAMPAIGN_CRITERION 6
الخلاصات
خلاصة الحملة CAMPAIGN_FEED 9
الخلاصة FEED 8
عنصر الخلاصة FEED_ITEM 10
المجموعات المشترَكة
المجموعة المشتركة SHARED_SET 17
المجموعة المشتركة للحملة CAMPAIGN_SHARED_SET 18
مواد العرض
مادة العرض ASSET 13
مجموعة مواد العرض ASSET_SET 25
مادة عرض العميل CUSTOMER_ASSET 14
مادة عرض الحملة CAMPAIGN_ASSET 15
مجموعة مواد العرض للحملة CAMPAIGN_ASSET_SET 26
مادة عرض المجموعة الإعلانية AD_GROUP_ASSET 16

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

يمكن أن تعرض Google Ads API صفوفًا تتضمّن قيمة نوع مرجع UNKNOWN للإصدارات السابقة من Google Ads 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.campaign, "
          + "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";

  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.V26.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: GoogleAdsClient, customer_id: str) -> None:
    ads_service: GoogleAdsServiceClient = 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: SearchGoogleAdsRequest = client.get_type(
        "SearchGoogleAdsRequest"
    )
    search_request.customer_id = customer_id
    search_request.query = query

    response: SearchPagedResponse = ads_service.search(request=search_request)

    row: GoogleAdsRow
    for row in response:
        cs: ChangeStatus = row.change_status
        resource_type: str = cs.resource_type.name
        resource_name: str
        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: str = 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,
  )

  # 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::V26::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 "";
  }
}

curl

المزامنة محليًا

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

تغيير الوقت

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

يُرجى العِلم أنّ هذا الحقل قابل للفلترة أيضًا، ما يعني أنّه يمكن استخدامه في عبارة WHERE لطلب بحث بلغة طلبات بحث إعلانات Google، ما يتيح لك طلب البحث عن التغييرات في المَراجع التي حدثت قبل وقت معيّن أو بعده.

على سبيل المثال، يمكن العثور على جميع التغييرات التي حدثت لنوع مرجع معيّن خلال الأسبوع الماضي باستخدام عبارة التوقّع التالية بلغة طلبات بحث Google Ads:

WHERE change_status.last_change_date_time DURING LAST_7_DAYS
السابق
ربط YouTube
التالي
تغيير الحدث