دارایی‌های مکان

برخلاف دارایی‌های دیگر، دارایی‌های مکان به‌طور خودکار توسط Google Ads API پس‌از ایجاد مجموعه دارایی ایجاد می‌شوند. ابتدا، یک مجموعه دارایی همگام‌سازی مکان ایجاد کنید و آن را به مشتری پیوست کنید. سپس، اگر لازم است زیرمجموعه‌ای از دارایی‌های مکان را در مجموعه دارایی برای پویش یا گروه آگهی انتخاب کنید، مجموعه دارایی گروه مکان ایجاد کنید و آن را به پویش یا گروه آگهی پیوست کنید.

مجموعه دارایی همگام‌سازی مکان ایجاد کنید و آن را به مشتری پیوست کنید

  1. مجموعه دارایی همگام‌سازی مکان ایجاد کنید.
  2. آن را بااستفاده از CustomerAssetSetService به مشتری پیوست کنید.

ایجاد مجموعه دارایی همگام‌سازی مکان

  1. AssetSet جدیدی ایجاد کنید.
    1. type را روی LOCATION_SYNC تنظیم کنید.
    2. ‫location_set را روی LocationSet جدیدی تنظیم کنید.

  2. در LocationSet جدید،

    1. ‫location_ownership_type را براساس مورد استفاده‌تان تنظیم کنید:
      • اگر مالک مکان کسب‌وکار هستید، آن را روی BUSINESS_OWNER تنظیم کنید.
      • اگر مالک مکان کسب‌وکار نیستید اما محصولاتتان را در آنجا می‌فروشید، آن را روی AFFILIATE تنظیم کنید.

    2. فیلد source oneof را براساس مورد استفاده‌تان تنظیم کنید:

      • اگر می‌خواهید با مکان‌هایتان در حساب نمایه کسب‌وکار Google همگام‌سازی کنید، business_profile_location_set را تنظیم کنید.

        وقتی BusinessProfileLocationSet ایجاد می‌کنید تا Google Ads را به حساب «نمایه کسب‌وکار Google» پیوند دهید، باید کد دسترسی OAuth 2.0 را در فیلد http_authorization_token ارائه دهید. این کد به‌عنوان مدرکی عمل می‌کند که به Google Ads اجازه می‌دهید به داده‌های مکان از «نمایه کسب‌وکار Google» مشخص‌شده دسترسی داشته باشد.

        توکن باید این الزامات را برآورده کند:

        • این کلید باید برای «حساب Google» (حساب کاربر یا خدمات) که نشانی ایمیل آن در فیلد email_address در BusinessProfileLocationSet ارائه شده است تولید شود.
        • این حساب باید اجازه‌های کافی برای خواندن مکان‌های کسب‌وکار در «نمایه کسب‌وکار Google» را داشته باشد.
        • کد OAuth 2.0 باید با https://www.googleapis.com/auth/business.manage scope به‌دست آید.

        برای دریافت دستورالعمل‌های دقیق درباره نحوه تولید کردن کد دسترسی OAuth 2.0، به استفاده از OAuth 2.0 برای دسترسی به Google APIs مراجعه کنید.

      • اگر می‌خواهید با مکان‌های موجود در شناسه‌های زنجیره مشخص‌شده همگام‌سازی کنید، chain_location_set را تنظیم کنید.

      • اگر می‌خواهید مکان‌ها را به‌صورت دستی بااستفاده از شناسه‌های مکان اضافه کنید، maps_location_set را تنظیم کنید.

پس‌از تکمیل این مراحل، Google Ads API دارایی‌های مکان را تولید می‌کند و آن‌ها را به مجموعه دارایی همگام‌سازی مکان ایجادشده برای شما اضافه می‌کند، مشابه زمانی که این کار را به‌صورت دستی بااستفاده از AssetSetAssetService انجام می‌دهید. نیازی نیست آن‌ها را دستکاری کنید، مگر اینکه بخواهید آن‌ها را به‌صورت دستی به مجموعه دارایی گروه مکان ایستا اضافه کنید.

فقط یک مجموعه دارایی همگام‌سازی مکان فعال با status تنظیم‌شده روی ENABLED می‌تواند برای مشتری وجود داشته باشد. اگر می‌خواهید نوع دیگری از مجموعه دارایی همگام‌سازی مکان ایجاد کنید، ابتدا مجموعه موجود را بردارید.

پیوست کردن مجموعه دارایی همگام‌سازی مکان به مشتری

از CustomerAssetSetService.MutateCustomerAssetSets برای پیوست کردن مجموعه دارایی همگام‌سازی مکان در بخش قبلی به مشتری‌تان استفاده کنید.

(اختیاری) مجموعه دارایی گروه مکان ایجاد کنید و آن را به پویش یا گروه آگهی پیوست کنید

مجموعه دارایی گروه مکان فقط درصورتی لازم است که بخواهید زیرمجموعه‌ای از دارایی‌های مکان را انتخاب کنید. این امر به‌دلیل پویش‌ها و گروه‌های آگهی است که دارایی‌های مکان را از سطح مشتری به ارث می‌برند.

مجموعه‌های دارایی گروه مکان حاوی زیرمجموعه‌ای از دارایی‌های مکان مجموعه دارایی همگام‌سازی مکان است. می‌توانید بااستفاده از برخی‌از ویژگی‌های «نمایه کسب‌وکار Google» (مثل فیلتر کردن براساس برچسب‌ها) یا شناسه‌های زنجیره‌ای و مکان‌های زنجیره‌ای، به‌طور پویا مجموعه دارایی گروه مکان ایجاد کنید. یا می‌توانید مجموعه دارایی گروه مکان را به‌صورت ایستا ایجاد کنید.

  1. مجموعه دارایی گروه مکان ایجاد کنید. مجموعه دارایی گروه مکان می‌تواند پویا یا ایستا باشد.
  2. بسته به نیازتان، مجموعه دارایی را به پویش یا گروه آگهی پیوست کنید.
  3. (اختیاری) دارایی‌های ازقبل تولیدشده را به مجموعه دارایی گروه مکان ایستا که به‌تازگی ایجاد شده است اضافه کنید.

برای یک مشتری معین، می‌توانید چندین مجموعه دارایی گروه مکان پویا یا ایستا ایجاد کنید.

ایجاد کردن مجموعه دارایی گروه مکان

AssetSet جدیدی ایجاد کنید و location_group_parent_asset_set_id را روی شناسه مجموعه دارایی همگام‌سازی مکان که قبلاً ایجاد شده است تنظیم کنید.

سپس، براساس اینکه می‌خواهید مجموعه دارایی گروه مکان پویا یا ایستا ایجاد کنید، چند فیلد را تنظیم کنید.

مجموعه‌های دارایی پویا

بسته به فیلدی که در LocationSet تنظیم کرده‌اید، فیلدها را براساس قانون زیر تنظیم کنید:

اگر فیلد زیر را تنظیم کنید سپس نوع را روی و این فیلد را به‌عنوان فیلد asset_set_source oneof تنظیم کنید
business_profile_location_set BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP business_profile_location_group
chain_location_set CHAIN_DYNAMIC_LOCATION_GROUP chain_location_group

اگر هنگام ایجاد دارایی همگام‌سازی مکان، maps_location_set را تنظیم کنید، نمی‌توانید مجموعه دارایی گروه مکان پویا ایجاد کنید. دلیل این است که مکان‌ها را به‌صورت دستی با «شناسه‌های مکان» اضافه کرده‌اید و هیچ ویژگی فیلتری برای استفاده در این نوع مکان‌ها وجود ندارد.

مجموعه‌های دارایی ایستا

type را روی STATIC_LOCATION_GROUP تنظیم کنید. می‌توانید مجموعه‌های دارایی گروه مکان ایستا را برای هر نوع مجموعه دارایی همگام‌سازی مکان ایجاد کنید، صرف‌نظر از اینکه چه فیلدهایی (business_profile_location_set، chain_location_set، یا maps_location_set) را در LocationSet تنظیم کرده باشید.

برای مجموعه‌های دارایی گروه مکان ایستا، باید دارایی‌های مکان تولیدشده را به‌صورت دستی به مجموعه‌های دارایی گروه مکان اضافه کنید.

مجموعه دارایی را به پویش یا گروه آگهی پیوست کنید

از CampaignAssetSetService.MutateCampaignAssetSets برای پیوست کردن مجموعه دارایی گروه مکان به پویش خود استفاده کنید.

یا اگر می‌خواهید مجموعه دارایی گروه مکان را به گروه آگهی پیوست کنید، از AdGroupAssetSetService.MutateAdGroupAssetSets استفاده کنید.

(اختیاری) دارایی‌های مکان را به مجموعه دارایی گروه مکان ایستا اضافه کنید

این مرحله فقط درصورتی لازم است که قبلاً مجموعه دارایی گروه مکان ایستا ایجاد کرده باشید.

  1. از گزارش asset_set_asset برای واکشی نام‌های منبع دارایی‌هایی که به‌طور خودکار برای مجموعه دارایی همگام‌سازی مکان قبلاً ایجادشده تولید شده‌اند استفاده کنید. از فیلتر کردن برای بازیابی فقط دارایی‌هایی که می‌خواهید استفاده کنید.
  2. آن‌ها را بااستفاده از AssetSetAssetService.MutateAssetSetAssets به مجموعه دارایی گروه مکان ایستا اضافه کنید.

مدیریت شناسه‌های مکان «نمایه کسب‌وکار»

وقتی از business_profile_location_set استفاده می‌کنید و listing_id_filters بازیابی‌شده از وب‌سایت یا میانای برنامه‌سازی کاربردی «نمایه کسب‌وکار» را فیلتر می‌کنید، ممکن است لازم باشد این مقادیر عددی را از نوع uint64 به int64 تبدیل کنید. اگر کد شما خطای زمان اجرایی تولید می‌کند که شناسه مکان «نمایه کسب‌وکار» شما هنگام افزودن آن به فیلد تکراری listing_id_filters[] خارج از محدوده است، احتمالاً باید آن را بااستفاده از هرکدام از مثال‌های زیر تبدیل کنید:

جاوا

/**
 * Converts the business profile location ID to the format expected by the
 * DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
 * The business profile location ID is an unsigned 64-bit integer, while the
 * listing_id_filters[] field expects signed 64-bit integers. This means that
 * for business profile location IDs that are out of range, we must perform the
 * two's complement to convert it into a signed int.
 *
 * @param businessProfileLocationId The ID of a Business Profile location ID.
 * @return a Business Profile location ID as a signed 64-bit integer (long).
 */
public static long convertBusinessProfileLocationId(String businessProfileLocationId) {
    return Long.parseUnsignedLong(businessProfileLocationId);
}

C#‎

/// <summary>
/// Converts the business profile location ID to the format expected by the
/// DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
/// The business profile location ID is an unsigned 64-bit integer, while the
/// listing_id_filters[] field expects signed 64-bit integers. This means that
/// for business profile location IDs that are out of range, we must perform the
/// two's complement to convert it into a signed int.
/// </summary>
/// <param name="businessProfileLocationId">The ID of a Business Profile location.</param>
/// <returns>The converted business location ID in signed 64 bit.</returns>
public long ConvertBusinessProfileLocationId(ulong businessProfileLocationId)
{
  return unchecked((long)businessProfileLocationId);
}

PHP

/**
* Converts a business profile location ID to a signed 64 bit integer.
*
* Converts the business profile location ID to the format expected by the
* DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
* The business profile location ID is an unsigned 64-bit integer, while the
* listing_id_filters[] field expects signed 64-bit integers. This means that
* for business profile location IDs that are out of range, we must perform the
* two's complement to convert it into a signed int.
*
* @param string $businessProfileLocationId the ID of a Business Profile location
* @return int the converted business location ID in signed 64 bit
*/
public static function convertBusinessProfileLocationId(string $businessProfileLocationId): int
{
    $unsignedMax = '18446744073709551615'; // 2^64 - 1
    $signedMax = '9223372036854775807'; // 2^63 - 1

    // Check if the business profile location ID is within 64 bit range.
    // If not, throw an error.
    if (bccomp($businessProfileLocationId, '0') < 0 || bccomp($businessProfileLocationId, $unsignedMax) > 0) {
        throw new InvalidArgumentException(
            'The given business profile location id is outside of the range for a 64 bit integer.'
        );
    }

    // Check if the business profile location ID is in signed 64 bit range.
    // If it's not, convert it to its two's complement.
    if (bccomp($businessProfileLocationId, $signedMax) > 0) {
        // Two's complement: ID - 2^64
        return (int) bcsub($businessProfileLocationId, '18446744073709551616');
    }

    return (int) $businessProfileLocationId;
}

Python

import ctypes

def convert_business_profile_location_id(business_profile_location_id):
    """Converts a business profile location ID to a signed 64 bit integer.

    Converts the business profile location ID to the format expected by the
    DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
    The business profile location ID is an unsigned 64-bit integer, while the
    listing_id_filters[] field expects signed 64-bit integers. This means that
    for business profile location IDs that are out of range, we must perform the
    two's complement to convert it into a signed int.

    Args:
        business_profile_location_id: the ID of a Business Profile location ID.

    Returns:
        a Business Profile location ID as a signed 64 bit integer.
    """
    # Check if the business profile location ID is within 64 bit range.
    # If not, throw an error.
    if business_profile_location_id < 0 or business_profile_location_id >= 2 ** 64:
        raise ValueError(
            "The given business profile location id is outside of the range for a 64 bit integer."
        )
    # Check if the business profile location ID is in signed 64 bit range.
    # If it's not, convert it to its two's complement.
    elif business_profile_location_id >= 2 ** 63:
        return ctypes.c_int64(business_profile_location_id).value
    else:
        return business_profile_location_id

Ruby

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
# Since Ruby supports arbitrary precision numbers, we have to calculate it
# manually.
LONG_MAX = 2 ** 63
ULONG_MAX = LONG_MAX * 2
def convert_business_profile_location_id(business_profile_location_id)
  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if business_profile_location_id < 0 || business_profile_location_id >= 2 ** 64
    raise "The given business profile location id is outside of the range for a 64 bit integer."
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  elsif business_profile_location_id >= 2**63
    -1 * (ULONG_MAX - business_profile_location_id)
  else
    business_profile_location_id
  end
end

پرل

use bigint;

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
sub convert_business_profile_location_id {
  my ($business_profile_location_id) = @_;

  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if ($business_profile_location_id < 0 || $business_profile_location_id >= 2**64) {
    die "The given business profile location id is outside of the range for a 64 bit integer";
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  } elsif ($business_profile_location_id >= 2**63) {
    return -1 * (2**64 - $business_profile_location_id);
  } else {
    return $business_profile_location_id;
  }
}
قبلی
ساخت و استفاده
بعدی
دارایی‌های خودکارسازی‌شده