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

Используйте сопоставления полей, чтобы перенести каждый этап работы со списками электронных адресов из 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. Это равносильно тому, что в Google Ads API для параметра upload_key_type задано значение CONTACT_INFO.
contact_id_info

Должен принимать значение ContactIdInfo.

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

Идентификаторы мобильных устройств

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

Должен принимать значение MobileIdInfo.

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

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

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

Должен принимать значение UserIdInfo.

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

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

В 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 не будет пройдена, 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 Нет эквивалента.
Назад
Как перейти на новую версию