تغییر وضعیت

ویدیو: وضعیت

ChangeStatus ابزاری برای پیگیری منابعی که در یک حساب درطول یک دوره زمانی مشخص تغییر کرده‌اند ارائه می‌دهد. اگر منبعی درطول دوره زمانی مشخص‌شده شما چندین تغییر داشته باشد، فقط آخرین تغییر برگردانده می‌شود. سپس می‌توانید تعیین کنید که آیا باید مقادیر پایگاه داده محلی خود را با مقادیری که در این دوره زمانی تغییر کرده‌اند همگام‌سازی کنید یا نه.

برای مثال، اگر درطول یک دوره زمانی مشخص، پویش خاصی را اضافه و سپس به‌روز کنید، فقط وضعیت تغییر برای عملیات UPDATE و نه برای عملیات ADD برگردانده می‌شود. اگر پایان چارچوب زمانی را به قبل‌از به‌روزرسانی منتقل کنید، عملیات ADD را خواهید دید.

اگر می‌خواهید نتایج کامل فیلدبه‌فیلد را با نمای دقیق ببینید، به ChangeEvent مراجعه کنید.

مهم: همه ردیف‌های وضعیت تغییر جزئیات مربوطه را در رویداد تغییر ندارند. محدودیت‌های رویداد تغییر را ببینید.

مهم: ممکن است برخی‌از ردیف‌های وضعیت تغییر در «سابقه تغییرات» در میانای وب Google Ads نشان داده نشود. واسط وب دارای منطق کسب‌وکار اضافی و قوانین پردازشی است که برونداد آن را در مقایسه با وضعیت تغییر تغییر می‌دهد.

آشنایی با دامنه تغییرات گزارش‌شده

وقتی ChangeStatus نشان‌دهنده تغییری در منبعی مثل CAMPAIGN باشد، یعنی خود منبع یا یکی از منابع فرعی آن (گروه آگهی، آگهی، یا معیار در آن پویش) اصلاح شده است.

منبع ChangeStatus با هدف ارائه نمای کلی گسترده‌ای از بخش‌هایی از حسابتان که فعالیت داشته‌اند طراحی شده است. اگر تغییری در منبع فرزند رخ دهد، شناسه منبع والد ممکن است برگردانده شود تا مطمئن شویم هیچ تغییری ازدست نمی‌رود. این امر به‌ویژه برای انواع منابعی که به‌طور صریح در enum 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
پویش	پویش	5
بودجه پویش	CAMPAIGN_BUDGET	7
معیار پویش	CAMPAIGN_CRITERION	6
فیدها
فید پویش	CAMPAIGN_FEED	9
فید	فید	8
عنصر فید	FEED_ITEM	10
مجموعه‌های هم‌رسانی‌شده
مجموعه مشترک	SHARED_SET	17
مجموعه هم‌رسانی‌شده پویش	CAMPAIGN_SHARED_SET	18
دارایی‌ها
دارایی	دارایی	13
مجموعه دارایی	ASSET_SET	25
دارایی مشتری	CUSTOMER_ASSET	14
دارایی پویش	CAMPAIGN_ASSET	15
مجموعه دارایی پویش	CAMPAIGN_ASSET_SET	26
دارایی گروه آگهی	AD_GROUP_ASSET	16

تعیین نوع منبع براساس شناسه

«میانای برنامه‌سازی کاربردی Google Ads» می‌تواند ردیف‌هایی با مقدار نوع منبع UNKNOWN برای نسخه‌های قدیمی‌تر «میانای برنامه‌سازی کاربردی» برگرداند، به این معنی که این نوع در نسخه جدیدتر «میانای برنامه‌سازی کاربردی Google Ads» پشتیبانی می‌شود اما وقتی نسخه قدیمی‌تر منتشر شد به‌طور کامل پشتیبانی نمی‌شد. وقتی این اتفاق می‌افتد، همچنان می‌توانید نوع منبع ردیف را با تجزیه کردن 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 نیز پر می‌شود.

ممکن است تا ۳ دقیقه طول بکشد تا تغییر در نتایج وضعیت تغییر نشان داده شود.

پرسمان باید براساس تاریخی در ۹۰ روز گذشته و به‌طور اختیاری براساس زمان فیلتر شود، و باید شامل عبارت LIMIT باشد که حداکثر روی ۱۰٬۰۰۰ نتیجه تنظیم شده باشد.

جاوا

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

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

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}"
        )
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,
  )

  # 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
      

پرل

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

فر کردن

توجه: اگرچه نمونه کد مستقیم REST برای این مرحله در اینجا ارائه نشده است، می‌توانید بااستفاده از درخواست REST دستی به این هدف دست یابید.

به اسناد میانای REST «میانای برنامه‌سازی کاربردی Google Ads» و صفحه‌های مرجع مختص روش مراجعه کنید. باید پایه‌بار JSON را براساس تعاریف proto بسازید.

منابع اصلی:

• استفاده از REST
• ساختار میانای REST
• نگاشت‌های فیلد JSON
• برای اطلاع از سرویس و روش خاص، به مرجع REST API مراجعه کنید.

همگام‌سازی محلی

پس‌از بازیابی resource_name دقیق، پُرسمان جدیدی با این نام منبع باید ساخته شود تا همه مقادیر فعلی منبع به‌دست آید. وضعیت تغییر برای مقادیر تغییریافته منبع خاصی پیگیری نمی‌شود—فقط کدام منابع تغییر کرده‌اند. برنامه فراخواننده مسئول تعیین تفاوت بین مقادیر قبلی و فعلی است.

تغییر دادن زمان

فیلد last_change_date_time نشان می‌دهد که آخرین تغییر در منبع چه زمانی رخ داده است. بنابراین، تازگی داده‌های ذخیره‌شده در حافظه نهان محلی را می‌توان با مقدار این فیلد مقایسه کرد تا به تعیین اینکه آیا داده‌های محلی قدیمی هستند یا نه کمک کند.

توجه داشته باشید که این فیلد فیلترپذیر نیز هست، یعنی می‌توان از آن در WHEREجمله پرسش زبان پُرسمان Google Ads (GAQL) استفاده کرد و به شما امکان می‌دهد تغییرات منابعی را که قبل یا بعداز زمان معینی رخ داده‌اند پُرسمان کنید.

برای مثال، پیدا کردن همه تغییراتی که برای نوع منبع خاصی در هفته گذشته رخ داده است می‌تواند با عبارت گزاره GAQL زیر انجام شود:

WHERE change_status.last_change_date_time DURING LAST_7_DAYS