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

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

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

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

Методы API

С помощью Data Manager API можно загружать каждую партию событий продаж в магазинах в одном файле IngestEventsRequest.

В Google Ads API для этого нужно было выполнить три шага с помощью OfflineUserDataJobService:

  1. Как создать задание с помощью CreateOfflineUserDataJob
  2. Добавьте операции в задание с помощью AddOfflineUserDataJobOperations.
  3. Как запустить задание с помощью RunOfflineUserDataJob

Поля запроса

Для каждого IngestEventsRequest действуют ограничения на количество запросов. Если количество операций в вашем запросе AddOfflineUserDataJobOperations превышает эти ограничения, вам нужно разделить его на несколько запросов к Data Manager API.

Ниже приведено сопоставление полей запросов Google Ads API с полями Data Manager API.

CreateOfflineUserDataJobRequest

В таблице ниже показано, как поля CreateOfflineUserDataJobRequest соотносятся с IngestEventsRequest.

CreateOfflineUserDataJobRequest (Google Ads API) IngestEventsRequest (Data Manager API) Примечания
customer_id destinations.operating_account Подробнее о полях клиентов и действий-конверсий…
  • Заголовок запроса developer-token
  • Заголовок запроса login-customer_id
  • Заголовок запроса linked-customer-id
 destinations Подробнее о полях клиентов и действий-конверсий…
  • job.status
  • job.failure_reason
 Диагностика Используйте request_id, возвращенный в IngestEventsResponse, чтобы получить диагностическую информацию о загрузке конверсий.
job.id request_id Используйте request_id, возвращенный в IngestEventsResponse, чтобы получить диагностическую информацию о загрузке конверсий.
job.external_id Ранее такого отчета не существовало
job.type Ранее такого отчета не существовало
job.store_sales_metadata.third_party_metadata.partner_id destinations.login_account Партнер по обработке данных, загружающий конверсии в результате продаж в магазине, определяется по login_account целевого местоположения. Подробнее о том, как настроить целевые страницы…
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time Ранее такого отчета не существовало
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction Ранее такого отчета не существовало
job.store_sales_metadata.third_party_metadata.partner_match_fraction Ранее такого отчета не существовало
job.store_sales_metadata.third_party_metadata.partner_upload_fraction Ранее такого отчета не существовало
job.store_sales_metadata.third_party_metadata.bridge_map_version_id Ранее такого отчета не существовало
job.store_sales_metadata.loyalty_fraction Ранее такого отчета не существовало
job.store_sales_metadata.transaction_upload_fraction Ранее такого отчета не существовало
job.store_sales_metadata.custom_key
  • events[].custom_variables[].variable
  • events[].cart_data.items[].custom_variables[].variable
 Сопоставьте с полем variable объекта CustomVariable на уровне события или ItemCustomVariable на уровне товара.
enable_match_rate_range_preview Ранее такого отчета не существовало
validate_only validate_only
Ранее такого отчета не существовало consent Google Ads API поддерживает указание consent только на уровне события в UserData. В Data Manager API можно указать согласие для всех событий в запросе, задав поле consent в IngestEventsRequest. Вы можете переопределить это значение для отдельного события, задав поле consent объекта Event.
Ранее такого отчета не существовало encoding Обязательно для загрузок UserData. Укажите Encoding, используемый для значений UserIdentifier.
Ранее такого отчета не существовало encryption_info Укажите, содержит ли запрос зашифрованные идентификаторы пользователей UserData. Подробнее о шифровании…

AddOfflineUserDataJobOperationsRequest

В таблице ниже показано, как поля AddOfflineUserDataJobOperationsRequest соотносятся с IngestEventsRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestEventsRequest (Data Manager API) Примечания
  • Заголовок запроса developer-token
  • Заголовок запроса login-customer_id
  • Заголовок запроса linked-customer-id
 destinations Подробнее о полях клиентов и действий-конверсий…
resource_name Ранее такого отчета не существовало Для Data Manager API не требуется обновлять ресурс задания.
enable_partial_failure Ранее такого отчета не существовало Если IngestEventsRequest выполняется успешно, любые сбои, возникающие при последующей обработке, обрабатываются на уровне события, что может привести к частичному успеху. Чтобы узнать статус загрузки, а также посмотреть ошибки и предупреждения для отдельных событий, используйте Диагностику. Если IngestEventsRequest не удается (например, из-за BadRequest), никакие события не обрабатываются. Вам нужно устранить ошибку и повторить запрос. Подробнее об ошибках API…
enable_warnings Ранее такого отчета не существовало Используйте Диагностику, чтобы получать предупреждения о запросах к Data Manager API. Включать ее не нужно.
operations events Операция OfflineUserDataJobOperation.create эквивалентна отправке IngestEventsRequest. Data Manager API не поддерживает удаление событий.
validate_only validate_only
Ранее такого отчета не существовало consent Google Ads API поддерживает указание consent только на уровне события в UserData. В Data Manager API можно указать согласие для всех событий в запросе, задав поле consent в IngestEventsRequest. Вы можете переопределить это значение для отдельного события, задав поле consent объекта Event.
Ранее такого отчета не существовало encoding Обязательно для загрузок UserData. Укажите Encoding, используемый для значений UserIdentifier.
Ранее такого отчета не существовало encryption_info Укажите, содержит ли запрос зашифрованные идентификаторы пользователей UserData. Подробнее о шифровании…

Поля клиентов и действий-конверсий

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

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

Google Ads API Destination (Data Manager API) Примечания
customer_id запроса operating_account Установите для параметра account_id идентификатор клиента аккаунта для обработки конверсий Google Рекламы. Задайте для параметра 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.
conversion_action product_destination_id Числовой идентификатор действия-конверсии. Не используйте название ресурса.

Поля типа обращения event

В таблице ниже показано, как поля конверсии в результате продаж в магазине соотносятся в двух API.

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

OfflineUserDataJobOperation.create (Google Ads API) Event (Data Manager API) Примечания
Ранее такого отчета не существовало event_source Обязательный атрибут. Для конверсий по продажам в магазине задайте значение IN_STORE.
transaction_attribute.conversion_action destinations.product_destination_id Подробнее о полях клиентов и действий-конверсий… Используйте числовой идентификатор действия-конверсии вместо названия ресурса.
transaction_attribute.transaction_date_time event_timestamp
  • Если вы используете формат JSON, задайте значение в формате RFC 3339, который немного отличается от формата даты и времени Google Ads API.
  • Если вы используете буферы протоколов, примените Timestamp и задайте поля seconds и (необязательно) nanoseconds.

Подробнее о формате временной метки…
transaction_attribute.transaction_amount_micros
  • conversion_value (обязательный)
  • cart_data.items[].conversion_value
 Укажите значение в валюте, а не в микроединицах. Например, если ценность конверсии составляет 5,23 долл.США, используйте значение 5.23.
transaction_attribute.currency_code currency Обязательно.
transaction_attribute.order_id transaction_id Обязательно.
transaction_attribute.store_attribute.store_code event_location.store_id Обязательный. Укажите код магазина в поле store_id объекта EventLocation.
transaction_attribute.custom_value
  • custom_variables[].value
  • cart_data.items[].custom_variables[].value
 Сопоставьте с полем value объекта CustomVariable на уровне события или ItemCustomVariable на уровне товара.
transaction_attribute.item_attribute.item_id cart_data.items[].merchant_product_id
transaction_attribute.item_attribute.merchant_id
  • cart_data.merchant_id
  • cart_data.items[].merchant_id
 Если вы зададите значение атрибута "доставка" cart_data.merchant_id, оно будет использоваться по умолчанию для всех товаров, но вы сможете переопределить его для отдельных позиций.
transaction_attribute.item_attribute.country_code
  • cart_data.merchant_feed_label
  • cart_data.items[].merchant_feed_label
 Если вы зададите значение атрибута "доставка" cart_data.merchant_feed_label, оно будет использоваться по умолчанию для всех товаров, но вы сможете переопределить его для отдельных позиций.
transaction_attribute.item_attribute.language_code
  • cart_data.merchant_feed_language_code
  • cart_data.items[].merchant_feed_language_code
 Если вы зададите значение атрибута "доставка" cart_data.merchant_feed_language_code, оно будет использоваться по умолчанию для всех товаров, но вы сможете переопределить его для отдельных позиций.
transaction_attribute.item_attribute.quantity cart_data.items[].quantity
Ранее такого отчета не существовало cart_data.items[].unit_price Цена товара без учета налогов, стоимости доставки и скидок на уровне события (транзакции).
user_identifiers
  • user_data.user_identifiers
  • third_party_user_data.user_identifiers
 Обязательный параметр.

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

Заполнять поле third_party_user_data можно, только если аккаунт для входа принадлежит партнеру по обработке данных (login_account.account_type – DATA_PARTNER).

Подробнее о полях идентификаторов пользователей…

consent consent В обоих API используется похожий объект Consent (ad_user_data, ad_personalization). В Data Manager API вы также можете задать согласие для всех событий в запросе, установив поле consent в IngestEventsRequest.

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

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

Источник определяет, какое поле будет заполнено в Data Manager API Event:

  • user_data
  • third_party_user_data

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

Заполнять поле third_party_user_data можно, только если аккаунт для входа принадлежит партнеру по обработке данных (login_account.account_type – DATA_PARTNER).

Подробнее о полях идентификаторов пользователей…

hashed_email email_address Установите форматированный и хешированный адрес электронной почты. Вы также можете зашифровать хешированный адрес электронной почты.
hashed_phone_number phone_number Отформатированный и хешированный номер телефона. Вы также можете зашифровать хешированный номер телефона.
address_info address Установите объект AddressInfo. Соблюдайте правила форматирования и хеширования. Вы также можете зашифровать хешированные атрибуты адреса.
address_info.hashed_first_name address.given_name
address_info.hashed_last_name address.family_name
address_info.country_code address.region_code
address_info.postal_code address.postal_code
address_info.city Ранее такого отчета не существовало Не поддерживается для целевых страниц Google Рекламы.
address_info.state Ранее такого отчета не существовало Не поддерживается для целевых страниц Google Рекламы.
address_info.hashed_street_address Ранее такого отчета не существовало Не поддерживается для целевых страниц Google Рекламы.
Назад
Как перейти на новую версию