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

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

Методы API

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

В отличие от этого, для работы с API Google Ads требовался трехэтапный процесс с использованием OfflineUserDataJobService :

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

Поля запроса

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

Вот как поля запросов к Google Ads API соотносятся с полями запросов к Data Manager API.

CreateOfflineUserDataJobRequest

В следующей таблице показано, как поля запроса CreateOfflineUserDataJobRequest сопоставляются с полями запроса IngestEventsRequest .

CreateOfflineUserDataJobRequest (Google Ads API) IngestEventsRequest (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 API Google Ads поддерживает указание consent только на уровне события в UserData . Для API Data Manager вы можете указать согласие для всех событий в запросе, установив поле consent в IngestEventsRequest . Вы можете переопределить это значение для отдельного события, установив поле consent в Event .
Нет эквивалента encoding Обязательно для загрузки UserData . Установите значение Encoding используемой для значений UserIdentifier .
Нет эквивалента encryption_info Установите этот параметр, если запрос содержит зашифрованные идентификаторы пользователей UserData . Подробнее см. в разделе «Шифрование» .

AddOfflineUserDataJobOperationsRequest

В следующей таблице показано, как поля объекта AddOfflineUserDataJobOperationsRequest сопоставляются с полями объекта IngestEventsRequest .

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

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

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

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

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

Поля событий

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

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

OfflineUserDataJobOperation.create (Google Ads API) Event (API менеджера данных) Примечания
Нет эквивалента event_source Для корректного отображения конверсии продаж в магазине необходимо установить значение IN_STORE .
transaction_attribute.conversion_action destinations.product_destination_id См. поля «Клиент» и «Действия конверсии» . Используйте числовой идентификатор действия конверсии вместо имени ресурса.
transaction_attribute.transaction_date_time event_timestamp
  • При использовании формата JSON укажите значение в формате RFC 3339 , который немного отличается от формата даты и времени API Google Ads .
  • При использовании протокола Protocol Buffers используйте метку 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 ). Для API Data Manager вы также можете установить согласие для всех событий в запросе, задав поле consent в объекте IngestEventsRequest .

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

UserIdentifier (API Google Ads) UserIdentifier (API менеджера данных) Примечания
user_identifier_source

Источник определяет, какое поле следует заполнить в Event API менеджера данных:

  • 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 Нет эквивалента В текущей версии API менеджера данных эта функция не поддерживается.
address_info.state Нет эквивалента В текущей версии API менеджера данных эта функция не поддерживается.
address_info.hashed_street_address Нет эквивалента В текущей версии API менеджера данных эта функция не поддерживается.
Назад
Шаги по обновлению