Объекты адресов

В отличие от других объектов, объекты адресов создаются 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. Задайте поле oneof source в зависимости от вашего варианта использования:

      • Задайте значение business_profile_location_set, если хотите синхронизировать данные с адресами из профиля компании в Google.

        При создании объекта BusinessProfileLocationSet для связывания Google Рекламы с профилем компании в Google необходимо указать токен доступа OAuth 2.0 в поле http_authorization_token. Этот токен подтверждает, что вы разрешаете Google Рекламе доступ к данным о местоположении из указанного профиля компании в Google.

        Токен должен соответствовать следующим требованиям:

        • Он должен быть сгенерирован для аккаунта Google (пользователя или сервисного аккаунта), адрес электронной почты которого указан в поле email_address файла BusinessProfileLocationSet.
        • У этого аккаунта должны быть разрешения на чтение адресов в профиле компании в Google.
        • Токен OAuth 2.0 должен быть получен с областью действия https://www.googleapis.com/auth/business.manage.

        Подробные инструкции по созданию токена доступа OAuth 2.0 приведены в статье Использование OAuth 2.0 для доступа к API Google.

      • Задайте значение 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, задайте поля на основе следующего правила:

Если вы зададите следующее поле Затем задайте для параметра type значение и задайте это поле как поле oneof asset_set_source.
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, полученные с сайта или через API профиля компании, может потребоваться преобразовать эти числовые значения из типа uint64 в int64. Если при добавлении идентификатора местоположения из профиля компании в повторяющееся поле listing_id_filters[] возникает ошибка выполнения, связанная с тем, что идентификатор выходит за пределы допустимого диапазона, преобразуйте его, как показано в примерах ниже.

Java

/**
 * 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

Perl

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;
  }
}
Назад
Создание и использование
Далее
Автоматические объекты