Сопоставления полей

Используйте сопоставление полей, чтобы перенести каждый шаг рабочего процесса со списками электронных адресов из Google Ads API в Data Manager API.

Аутентификация

Для Data Manager API требуются учетные данные с другой областью действия, чем для Google Ads API. Следуйте инструкциям в статье Как настроить доступ к API, чтобы создать новые учетные данные, включающие область действия Data Manager API.

Сопоставления полей для управления аудиториями

Используйте сопоставления в таблицах, чтобы сопоставить UserList в Google Ads API с эквивалентным UserList в Data Manager API.

UserList (Google Ads API) UserList (Data Manager API) Примечания
resource_name name Подробнее о названиях ресурсов…
id id
read_only read_only
name display_name Обязательно
description description Обязательно
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

Период, в течение которого участник аудитории остается в списке после добавления. Значение должно соответствовать целым дням. Если значение не задано, по умолчанию используется максимальное.

Значение должно быть указано в формате временной метки.
size_for_display size_info.display_network_members_count
size_range_for_display Нет эквивалента. Используйте атрибут size_info.display_network_members_count для указания размера.
size_for_search size_info.search_network_members_count
size_range_for_search Нет эквивалента. Используйте атрибут size_info.search_network_members_count для указания размера.
type Нет эквивалента.
access_reason access_reason
account_user_list_status account_access_status
closing_reason closing_reason
eligible_for_search target_network_info.eligible_for_search
eligible_for_display target_network_info.eligible_for_display
match_rate_percentage ingested_user_list_info.contact_id_info.match_rate_percentage
basic_user_list ingested_user_list_info.pseudonymous_id_info Не используется для списков электронных адресов.
crm_based_user_list ingested_user_list_info Обязательно. Подробнее об аудиториях на основе списков электронных адресов…
Нет эквивалента. ingested_user_list_info.pair_id_info Не используется для списков электронных адресов.
Нет эквивалента. ingested_user_list_info.partner_audience_info Не используется для списков электронных адресов.
logical_user_list Нет эквивалента. Не используется для списков электронных адресов.
logical_user_list Нет эквивалента. Не используется для списков электронных адресов.
lookalike_user_list Нет эквивалента. Не используется для списков электронных адресов.
rule_based_user_list Нет эквивалента. Не используется для списков электронных адресов.
similar_user_list Нет эквивалента. Не используется для списков электронных адресов.

Информация об аудиториях на основе списков электронных адресов

При создании аудитории на основе списка электронных адресов в Google Ads API необходимо задать для поля crm_based_user_list значение CrmBasedUserListInfo.

В Data Manager API задайте эквивалентные атрибуты, установив для поля ingested_user_list_info значение IngestedUserListInfo, а затем задайте обязательные поля для списков электронных адресов и типа пользовательских данных.

Контактная информация

upload_key_types
Задайте список, содержащий CONTACT_ID. Это эквивалентно установке значения upload_key_type для CONTACT_INFO в Google Ads API.
contact_id_info

Установите значение ContactIdInfo.

Задайте для параметра data_source_type значение DATA_SOURCE_TYPE_FIRST_PARTY. Это эквивалентно установке значения data_source_type для FIRST_PARTY в Google Ads API.

Электронные удостоверения личности

upload_key_types
Задайте список, содержащий MOBILE_ID. Это эквивалентно установке значения upload_key_type для MOBILE_ADVERTISING_ID в Google Ads API.
mobile_id_info

Установите значение MobileIdInfo.

  • Задайте для параметра data_source_type значение DATA_SOURCE_TYPE_FIRST_PARTY. Это эквивалентно установке значения FIRST_PARTY для data_source_type в Google Ads API.
  • Присвойте key_space значение IOS или ANDROID. Это значение требуется для Data Manager API. В Google Ads API пространство ключей определяется полем app_id.
  • В качестве значения параметра app_id укажите строку, которая однозначно идентифицирует мобильное приложение, из которого были собраны данные. Используйте тот же формат, что и для app_id в Google Ads API.

идентификаторы пользователей;

upload_key_types
Задайте список, содержащий USER_ID. Это эквивалентно установке значения upload_key_type для CRM_ID в Google Ads API.
user_id_info

Установите значение UserIdInfo.

Задайте для параметра data_source_type значение DATA_SOURCE_TYPE_FIRST_PARTY. Это эквивалентно установке значения FIRST_PARTY для data_source_type в Google Ads API.

Названия ресурсов

В Data Manager API используется другой формат названия ресурса, чем в Google Ads API.

Google Ads API

В Google Ads API название ресурса UserList имеет следующий формат:

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

В Data Manager API название ресурса UserList имеет следующий формат:

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

Загрузить сопоставления полей

Используйте сопоставления в таблицах, чтобы сопоставить AddOfflineUserDataJobOperationsRequest в Google Ads API с эквивалентным запросом IngestionService в Data Manager API.

Поля запроса

Эти сопоставления используют IngestAudienceMembersRequest в Data Manager API в качестве ссылки, но вы также можете использовать их, если преобразуете запрос Google Ads API в RemoveAudienceMembersRequest или RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) Примечания
  • Поле customer_id
  • Поле customer_match_user_list_metadata в OfflineUserDataJob
  • Заголовок запроса developer-token
  • Заголовок запроса login-customer_id
  • Заголовок запроса linked-customer-id
 destinations Подробнее о полях клиентов и аудиторий…
consent из customer_match_user_list_metadata в OfflineUserDataJob consent Необязательные настройки согласия по умолчанию для участников аудитории в запросе. Это значение можно переопределить для отдельного участника аудитории, задав поле consent объекта AudienceMember.
Ранее такого отчета не существовало encoding Обязательный. Укажите Encoding, используемый для значений UserIdentifier.
Ранее такого отчета не существовало encryption_info Укажите, содержит ли запрос зашифрованные значения. Подробнее о шифровании…
job_id Ранее такого отчета не существовало Используйте значение request_id, возвращенное в ответе, чтобы получить диагностические данные.
enable_partial_failure Ранее такого отчета не существовало В Data Manager API используется модель ошибок с быстрым отказом. Если какое-либо поле IngestAudienceMembersRequest не проходит проверку, Data Manager API отклоняет весь запрос. Получите информацию об ошибках обработки с помощью диагностики.
enable_warnings Ранее такого отчета не существовало В ответе Data Manager API не сообщает о предупреждениях. Получите предупреждения об обработке с помощью диагностики.
validate_only validate_only
operations audience_members Список участников аудитории, которых нужно добавить или удалить. Подробную информацию вы найдете в разделе Поля операции.
Ранее такого отчета не существовало terms_of_service Обязательно. Указывает, принял ли пользователь условия использования списков электронных адресов.

Поля клиентов и аудиторий

Google Ads API поддерживает загрузку участников только в одну аудиторию за задание.Кроме того, требуется заголовок запроса developer-token, а заголовки запросов login-customer-id и linked-customer-id задаются для разных сценариев аутентификации.

Data Manager API поддерживает отправку участников нескольких аудиторий в одном запросе. Для Data Manager API не требуется токен разработчика, а данные для входа и информация о связанных клиентах указываются в полях Destination, а не в заголовках запросов. Подробнее о настройке целевых сервисов…

В Google Ads API можно удалить всех участников аудитории, задав для поля remove_all объекта OfflineUserDataJobOperation значение true.

В Data Manager API для этого нужно отправить запрос RemoveAllAudienceMembersRequest. Подробные инструкции приведены в разделе Как удалить всех участников.

Ниже описано, как сопоставить поля Google Ads API для одной аудитории с эквивалентными полями в Destination.

Google Ads API Destination (Data Manager API) Примечания
customer_id запроса operating_account В поле account_id укажите идентификатор клиента аудитории. Задайте для свойства account_type объекта operating_account значение GOOGLE_ADS.
Заголовок запроса developer-token Ранее такого отчета не существовало Для Data Manager API токен разработчика не требуется.
Заголовок запроса login-customer-id login_account В качестве значения account_id укажите идентификатор клиента для аккаунта, используемого для входа. Задайте для account_type значение GOOGLE_ADS, если аккаунт для входа – это аккаунт Google Рекламы, или DATA_PARTNER, если это аккаунт партнера по обработке данных.
Заголовок запроса linked-customer-id linked_account Если вы получаете доступ к operating_account с помощью партнерской ссылки, задайте для account_id идентификатор клиента связанного аккаунта, а для account_type – значение DATA_PARTNER. В противном случае не задавайте поле linked_account.
user_list из customer_match_user_list_metadata OfflineUserDataJob product_destination_id Обязательно. Укажите числовой идентификатор аудитории. Не используйте название ресурса UserList.
Ранее такого отчета не существовало reference Определенный пользователем идентификатор для Destination. Задайте это поле, если вы отправляете участников нескольких аудиторий в одном запросе.

Поля операций

В Data Manager API есть отдельные методы для добавления и удаления участников аудитории. В отличие от этого, объект AddOfflineUserDataJobOperationsRequest в Google Ads API содержит список объектов operations, каждый из которых добавляет или удаляет одного или всех участников в зависимости от типа операции. Ниже показано, как каждый тип операции сопоставляется с соответствующим методом в Data Manager API.

OfflineUserDataJobOperation (Google Ads API) Метод IngestionService (Data Manager API) Примечания
create IngestAudienceMembers Подробную информацию вы найдете в разделе Поля участников аудитории.
remove RemoveAudienceMembers Подробную информацию вы найдете в разделе Поля участников аудитории.
remove_all RemoveAllAudienceMembers Подробнее о том, как удалить всех участников аудитории…

Поля участников аудитории

UserData (Google Ads API) AudienceMember (Data Manager API) Примечания
consent consent

Укажите согласие для участника аудитории.

Оба API используют похожий объект Consent (ad_user_data, ad_personalization).

В Data Manager API вы также можете задать согласие для всех участников аудитории в запросе, указав поле consent на уровне запроса.
transaction_attribute Нет эквивалента. Неприменимо к спискам электронных адресов.
user_attribute Нет эквивалента. Неприменимо к спискам электронных адресов.
user_identifiers
  • mobile_data
  • user_id_data
  • composite_data
    • user_data
    • ip_data

Заполните поле, соответствующее типу данных, которые вы отправляете для участников аудитории. Подробнее о полях идентификатора пользователя…

Поля с идентификатором пользователя

В Google Ads API для отправки контактной информации, идентификаторов мобильных устройств или идентификаторов пользователей используется UserIdentifier. В Data Manager API используется другой подход, при котором для каждого типа данных предусмотрены разные поля.

В Data Manager API заполните поле, соответствующее типу данных, которые вы отправляете:

Контактная информация

Если вы используете контактную информацию, например адрес электронной почты, номер телефона или почтовый адрес, задайте для свойства composite_data значение CompositeData с отдельной записью в свойстве user_data.user_identifiers для каждого элемента контактной информации.

Хотя user_data по-прежнему поддерживается, мы рекомендуем использовать composite_data, чтобы обеспечить совместимость с будущими улучшениями. Подробнее о составных данных…

UserIdentifier (Google Ads API) UserIdentifier (Data Manager API) Примечания
address_info address Подробнее о полях адреса…
hashed_email email_address Укажите отформатированный и хешированный адрес электронной почты. Вы также можете зашифровать хешированный адрес электронной почты.
hashed_phone_number phone_number Укажите отформатированный и хешированный номер телефона. Вы также можете зашифровать хешированный номер телефона.
user_identifier_source Нет эквивалента.

Поля адреса

Ниже приведены сопоставления полей между OfflineUserAddressInfo в Google Ads API и AddressInfo в Data Manager API. Используйте эти сопоставления, если вы используете контактную информацию для заполнения аудитории на основе списка эл. адресов.

OfflineUserAddressInfo (Google Ads API) AddressInfo (Data Manager API) Примечания
city Нет эквивалента.
country_code region_code Обязательно
hashed_first_name given_name

Обязательно. Укажите отформатированное и хешированное имя. Вы также можете зашифровать хешированное имя.
hashed_last_name family_name

Обязательно. Укажите отформатированную и хешированную фамилию. Вы также можете зашифровать хешированную фамилию.
hashed_street_address Нет эквивалента.
postal_code postal_code Обязательно
state Нет эквивалента.

IP-адрес

Data Manager API позволяет добавлять IP-адреса в списки электронных адресов вместе с идентификаторами пользователей. Они предоставляются в CompositeData, который объединяет UserData и IpData. Если вы укажете оба поля, это может повысить коэффициент соответствия.

Подробнее о передаче IP-адресов для списков электронных адресов…

Google Ads API CompositeData (Data Manager API) Примечания
Нет эквивалента. ip_data.ip_address Укажите необработанный адрес IPv4 или IPv6. Ознакомьтесь с рекомендациями по формату IP-адресов.
Нет эквивалента. ip_data.observe_start_time Укажите временную метку в формате RFC 3339, когда IP-адрес был зарегистрирован впервые.
Нет эквивалента. ip_data.observe_end_time Временная метка в формате RFC 3339, когда IP-адрес был зафиксирован в последний раз.
user_identifiers user_data Задайте объект UserData.

Электронные удостоверения личности

Если вы используете мобильные идентификаторы, задайте для mobile_data значение MobileData с записью в mobile_ids для каждого идентификатора.

UserIdentifier (Google Ads API) MobileData (Data Manager API) Примечания
mobile_id mobile_ids Задайте список мобильных идентификаторов для участника аудитории.

В Google Ads API вы добавляете отдельный объект UserIdentifier с mobile_id для каждого идентификатора мобильного устройства участника аудитории. В Data Manager API добавьте один объект MobileData, в котором для mobile_ids задан список всех идентификаторов мобильных устройств участника аудитории.

user_identifier_source Нет эквивалента.

идентификаторы пользователей;

Если вы используете идентификаторы пользователей, задайте для user_id_data значение UserIdData, а для user_id – идентификатор пользователя, который является участником аудитории.

UserIdentifier (Google Ads API) UserIdData (Data Manager API) Примечания
third_party_user_id user_id

В Google Ads API вы добавляете отдельный объект UserIdentifier с third_party_user_id для каждого идентификатора пользователя, входящего в аудиторию.

В Data Manager API задайте для поля user_id_data значение UserIdData, а для поля user_id – идентификатор пользователя, который является участником аудитории. Нельзя отправлять несколько идентификаторов для одного участника аудитории.

user_identifier_source Нет эквивалента.
Назад
Как перейти на новую версию