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

Используйте сопоставления в таблицах, чтобы сопоставить методы и поля 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 Рекламы.
Назад
Как перейти на новую версию