Mapeamentos de campo

Use os mapeamentos nas tabelas para mapear os métodos e campos da API Google Ads para o equivalente IngestEventsRequest na API Data Manager.

Métodos da API

Com a API Data Manager, é possível fazer o upload de cada lote de eventos de vendas na loja em uma única IngestEventsRequest.

Em contraste, a API Google Ads exigia um processo de três etapas usando o OfflineUserDataJobService:

  1. Criar um job usando CreateOfflineUserDataJob
  2. Adicionar operações ao job usando AddOfflineUserDataJobOperations
  3. Executar o job usando o RunOfflineUserDataJob

Campos de solicitação

Cada IngestEventsRequest está sujeito a limites de solicitação. Se o número de operações na sua solicitação AddOfflineUserDataJobOperations exceder esses limites, divida em várias solicitações de ingestão da API Data Manager.

Confira como os campos das solicitações da API Google Ads são mapeados para a API Data Manager.

CreateOfflineUserDataJobRequest

A tabela a seguir mostra como os campos de um CreateOfflineUserDataJobRequest são mapeados para um IngestEventsRequest.

CreateOfflineUserDataJobRequest (API Google Ads) IngestEventsRequest (API Data Manager) Observações
customer_id destinations.operating_account Consulte Campos de cliente e ação de conversão.
  • Cabeçalho da solicitação developer-token
  • Cabeçalho da solicitação login-customer_id
  • Cabeçalho da solicitação linked-customer-id
 destinations Consulte Campos de cliente e ação de conversão.
  • job.status
  • job.failure_reason
 Diagnóstico Use o request_id retornado no IngestEventsResponse para recuperar diagnósticos sobre o upload de conversão.
job.id request_id Use o request_id retornado no IngestEventsResponse para recuperar diagnósticos sobre o upload de conversão.
job.external_id Não há equivalente
job.type Não há equivalente
job.store_sales_metadata.third_party_metadata.partner_id destinations.login_account Um parceiro de dados que faz upload de conversões de vendas na loja é identificado pelo login_account de um destino. Consulte Configurar destinos para mais detalhes.
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time Não há equivalente
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction Não há equivalente
job.store_sales_metadata.third_party_metadata.partner_match_fraction Não há equivalente
job.store_sales_metadata.third_party_metadata.partner_upload_fraction Não há equivalente
job.store_sales_metadata.third_party_metadata.bridge_map_version_id Não há equivalente
job.store_sales_metadata.loyalty_fraction Não há equivalente
job.store_sales_metadata.transaction_upload_fraction Não há equivalente
job.store_sales_metadata.custom_key
  • events[].custom_variables[].variable
  • events[].cart_data.items[].custom_variables[].variable
 Mapeie para o campo variable de um CustomVariable no nível do evento ou um ItemCustomVariable no nível do item.
enable_match_rate_range_preview Não há equivalente
validate_only validate_only
Não há equivalente consent A API Google Ads só permite especificar consent no nível do evento em UserData. Para a API Data Manager, é possível especificar o consentimento para todos os eventos em uma solicitação definindo o campo consent no IngestEventsRequest. É possível substituir esse valor em um evento específico definindo o campo consent de Event.
Não há equivalente encoding Obrigatório para uploads de UserData. Definido como o Encoding usado para valores de UserIdentifier.
Não há equivalente encryption_info Definido se a solicitação contém identificadores de usuário UserData criptografados. Consulte Criptografia para mais detalhes.

AddOfflineUserDataJobOperationsRequest

A tabela a seguir mostra como os campos de um AddOfflineUserDataJobOperationsRequest são mapeados para um IngestEventsRequest.

AddOfflineUserDataJobOperationsRequest (API Google Ads) IngestEventsRequest (API Data Manager) Observações
  • Cabeçalho da solicitação developer-token
  • Cabeçalho da solicitação login-customer_id
  • Cabeçalho da solicitação linked-customer-id
 destinations Consulte Campos de cliente e ação de conversão.
resource_name Não há equivalente A API Data Manager não exige a atualização de um recurso de job.
enable_partial_failure Não há equivalente Se o IngestEventsRequest for bem-sucedido, as falhas que ocorrerem durante o processamento downstream serão tratadas no nível do evento, o que pode resultar em um sucesso parcial. Use Diagnóstico para recuperar o status do seu upload, além de erros e avisos de eventos individuais. Se o IngestEventsRequest falhar (por exemplo, devido a um BadRequest), nenhum evento será processado. Você precisará resolver o erro e tentar fazer a solicitação novamente. Consulte Entender erros de API para mais informações.
enable_warnings Não há equivalente Use Diagnóstico para recuperar avisos sobre sua solicitação de API do Data Manager. Não é necessário ativar esse recurso.
operations events A operação OfflineUserDataJobOperation.create equivale a enviar um IngestEventsRequest. A API Data Manager não permite remover eventos.
validate_only validate_only
Não há equivalente consent A API Google Ads só permite especificar consent no nível do evento em UserData. Para a API Data Manager, é possível especificar o consentimento para todos os eventos em uma solicitação definindo o campo consent no IngestEventsRequest. É possível substituir esse valor em um evento específico definindo o campo consent de Event.
Não há equivalente encoding Obrigatório para uploads de UserData. Definido como o Encoding usado para valores de UserIdentifier.
Não há equivalente encryption_info Definido se a solicitação contém identificadores de usuário UserData criptografados. Consulte Criptografia para mais detalhes.

Campos de cliente e ação de conversão

A API Google Ads exige o cabeçalho de solicitação developer-token, e você define os cabeçalhos de solicitação login-customer-id e linked-customer-id para diferentes cenários de autenticação.

A API Data Manager não exige um token de desenvolvedor, e você especifica o login e as informações do cliente vinculado usando campos de um Destination em vez de cabeçalhos de solicitação. Confira Configurar destinos para mais informações sobre destinos.

API Google Ads Destination (API Data Manager) Observações
customer_id da solicitação operating_account Defina o account_id como o ID de cliente da conta de conversão do Google Ads. Defina o account_type do operating_account como GOOGLE_ADS.
Cabeçalho da solicitação developer-token Não há equivalente Um token de desenvolvedor não é necessário para a API Data Manager.
Cabeçalho da solicitação login-customer-id login_account Defina o account_id como o ID de cliente da conta de login. Defina account_type como GOOGLE_ADS se a conta de login for uma conta do Google Ads ou DATA_PARTNER se for uma conta de parceiro de dados.
Cabeçalho da solicitação linked-customer-id linked_account Se você estiver acessando o operating_account usando um link de parceiro, defina o account_id como o ID do cliente da conta vinculada e defina account_type como DATA_PARTNER. Caso contrário, não defina o campo linked_account.
conversion_action product_destination_id Definido como o ID numérico da ação de conversão. Não use o nome do recurso.

Campos de evento

A tabela a seguir mostra como os campos de uma conversão de vendas na loja são mapeados entre as duas APIs.

Ao contrário da API Google Ads, que permite incluir apenas um item por transação usando ItemAttribute, a API Data Manager permite incluir vários itens por evento em CartData.

OfflineUserDataJobOperation.create (API Google Ads) Event (API Data Manager) Observações
Não há equivalente event_source Obrigatório. Defina como IN_STORE para conversões de vendas na loja.
transaction_attribute.conversion_action destinations.product_destination_id Consulte Campos de cliente e ação de conversão. Use o ID numérico da ação de conversão em vez do nome do recurso.
transaction_attribute.transaction_date_time event_timestamp
Consulte Formato do carimbo de data/hora para mais detalhes.
transaction_attribute.transaction_amount_micros
  • conversion_value (obrigatório)
  • cart_data.items[].conversion_value
 Defina como o valor da moeda, não o valor em micros. Por exemplo, para um valor de conversão de R $5,23, use o valor 5.23.
transaction_attribute.currency_code currency Obrigatório.
transaction_attribute.order_id transaction_id Obrigatório.
transaction_attribute.store_attribute.store_code event_location.store_id Obrigatório: defina o código da loja no campo store_id do objeto EventLocation.
transaction_attribute.custom_value
  • custom_variables[].value
  • cart_data.items[].custom_variables[].value
 Mapeie para o campo value de um CustomVariable no nível do evento ou um ItemCustomVariable no nível do item.
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
 Se você definir cart_data.merchant_id, ele vai funcionar como padrão para todos os itens, mas poderá ser substituído em itens individuais.
transaction_attribute.item_attribute.country_code
  • cart_data.merchant_feed_label
  • cart_data.items[].merchant_feed_label
 Se você definir cart_data.merchant_feed_label, ele vai funcionar como padrão para todos os itens, mas poderá ser substituído em itens individuais.
transaction_attribute.item_attribute.language_code
  • cart_data.merchant_feed_language_code
  • cart_data.items[].merchant_feed_language_code
 Se você definir cart_data.merchant_feed_language_code, ele vai funcionar como padrão para todos os itens, mas poderá ser substituído em itens individuais.
transaction_attribute.item_attribute.quantity cart_data.items[].quantity
Não há equivalente cart_data.items[].unit_price Definido como o preço unitário, excluindo tributos, frete e descontos no nível da transação para este item.
user_identifiers
  • user_data.user_identifiers
  • third_party_user_data.user_identifiers
 Obrigatório.

third_party_user_data usa a mesma estrutura de user_data, mas indica que os identificadores de usuário vêm de uma fonte de terceiros, em vez de dados próprios do anunciante.

O preenchimento de third_party_user_data só é permitido se a conta de login for um parceiro de dados (login_account.account_type for DATA_PARTNER).

Consulte Campos de identificador do usuário para mais detalhes.

consent consent As duas APIs usam um objeto Consent (ad_user_data, ad_personalization) semelhante. Para a API Data Manager, também é possível definir o consentimento para todos os eventos em uma solicitação definindo o campo consent no IngestEventsRequest.

Campos do identificador de usuário

UserIdentifier (API Google Ads) UserIdentifier (API Data Manager) Observações
user_identifier_source

A origem determina qual campo preencher na API Data Manager Event:

  • user_data
  • third_party_user_data

third_party_user_data usa a mesma estrutura de user_data, mas indica que os identificadores de usuário vêm de uma fonte de terceiros, em vez de dados próprios do anunciante.

O preenchimento de third_party_user_data só é permitido se a conta de login for um parceiro de dados (login_account.account_type for DATA_PARTNER).

Consulte Campos de identificador do usuário para mais detalhes.

hashed_email email_address Definido como o endereço de e-mail formatado e com hash. Também é possível criptografar o endereço de e-mail com hash.
hashed_phone_number phone_number Definido como o número de telefone formatado e com hash. Também é possível criptografar o número de telefone com hash.
address_info address Definido como um objeto AddressInfo. Siga as diretrizes de formatação e hash. Também é possível criptografar os atributos hash de um endereço.
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 Não há equivalente Indisponível na versão atual da API Data Manager.
address_info.state Não há equivalente Indisponível na versão atual da API Data Manager.
address_info.hashed_street_address Não há equivalente Indisponível na versão atual da API Data Manager.
Anterior
Etapas para o upgrade