В отличие от других объектов, объекты адресов автоматически создаются Google Ads API после того, как вы создадите набор объектов. Сначала создайте набор объектов синхронизации адресов и свяжите его с клиентом. Затем, если вам нужно выбрать подмножество объектов адресов в наборе объектов для кампании или группы объявлений, создайте набор объектов группы адресов и прикрепите его к кампании или группе объявлений.
Создайте набор объектов синхронизации адресов и свяжите его с клиентом
- Создайте набор объектов синхронизации адресов.
- Прикрепите его к клиенту, используя
CustomerAssetSetService.
Как создать набор объектов для синхронизации адресов
- Создайте новый
AssetSet.- Задайте для параметра
typeзначениеLOCATION_SYNC. - Задайте для
location_setновый объектLocationSet.
- Задайте для параметра
В новом интерфейсе
LocationSet- Установите значение
location_ownership_typeв зависимости от вашего варианта использования:- Если вы владелец компании, задайте значение
BUSINESS_OWNER. - Если вы не владеете адресом компании, но продаете там свои товары, задайте значение
AFFILIATE.
- Если вы владелец компании, задайте значение
Задайте поле
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.
- Его необходимо создать для аккаунта Google (пользователя или сервисного аккаунта), адрес электронной почты которого указан в поле
Укажите
chain_location_set, если хотите синхронизировать данные с адресами в цепочках с указанными идентификаторами.Установите значение
maps_location_set, если вы хотите вручную добавлять местоположения, используя идентификаторы мест.
- Установите значение
После выполнения этих шагов Google Ads API генерирует объекты адресов и добавляет их в созданный набор объектов синхронизации адресов, как если бы вы сделали это вручную с помощью AssetSetAssetService. Вам не нужно изменять их, если вы не хотите вручную добавить их в набор объектов статической группы адресов.
У клиента может быть только один активный набор объектов синхронизации адресов, в котором для параметра status задано значение ENABLED. Если вам нужно создать набор объектов синхронизации адресов другого типа, сначала удалите существующий.
Как прикрепить набор объектов синхронизации адресов к клиенту
Используйте
CustomerAssetSetService.MutateCustomerAssetSets
чтобы прикрепить набор объектов синхронизации местоположений, созданный в предыдущем разделе, к клиенту.
Как создать набор объектов группы адресов и связать его с кампанией или группой объявлений (необязательно)
Набор объектов группы адресов необходим только в том случае, если вам нужно выбрать подмножество объектов адресов. Это связано с тем, что кампании и группы объявлений наследуют объекты адресов на уровне клиента.
Наборы объектов групп адресов содержат подмножество объектов адресов из набора объектов синхронизации адресов. Вы можете динамически создать набор объектов группы адресов, используя некоторые функции профиля компании в Google (например, фильтрацию по ярлыкам) или идентификаторы и адреса сетей. Вы также можете создать набор объектов группы адресов статически.
- Создайте набор объектов группы адресов. Набор объектов группы адресов может быть динамическим или статическим.
- Прикрепите набор объектов к кампании или группе объявлений в зависимости от ваших потребностей.
- (Необязательно.) Добавьте ранее сгенерированные объекты в новый набор объектов группы статических адресов.
Для данного клиента можно создать несколько наборов объектов для динамических или статических групп адресов.
Как создать набор объектов группы адресов
Создайте новый объект 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.
Добавьте объекты адресов в статический набор объектов группы адресов (необязательно)
Этот шаг необходим, только если вы ранее создали набор объектов статической группы адресов.
- Используйте отчет
asset_set_asset, чтобы получить названия ресурсов объектов, автоматически созданных для ранее созданного набора объектов синхронизации адресов. Чтобы получить только нужные объекты, используйте фильтрацию. - Добавьте их в набор объектов статической группы адресов с помощью
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;
}
}