Mapeamentos de campo

Use os mapeamentos de campo para fazer upgrade de cada etapa do seu fluxo de trabalho de Segmentação por lista de clientes da API Google Ads para a API Data Manager:

Autenticação

A API Data Manager exige credenciais com um escopo diferente da API Google Ads. Siga as etapas em Configurar o acesso à API para gerar novas credenciais que incluem o escopo da API Data Manager.

Mapeamentos de campo do gerenciamento de público-alvo

Use os mapeamentos nas tabelas para mapear um UserList na API Google Ads para o equivalente UserList na API Data Manager.

UserList (API Google Ads) UserList (API Data Manager) Observações
resource_name name Consulte Nomes de recursos para mais detalhes.
id id
read_only read_only
name display_name Obrigatório
description description Obrigatório
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

O período em que um membro do público-alvo permanece na lista depois de ser adicionado. O valor precisa corresponder a dias inteiros. Se não for definido, o padrão será o máximo.

Formate o valor usando o formato de carimbo de data/hora.
size_for_display size_info.display_network_members_count
size_range_for_display Não há equivalente. Use o size_info.display_network_members_count para informações de tamanho.
size_for_search size_info.search_network_members_count
size_range_for_search Não há equivalente. Use o size_info.search_network_members_count para informações de tamanho.
type Não há equivalente.
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 Não é usado para a Segmentação por lista de clientes.
crm_based_user_list ingested_user_list_info Obrigatório. Consulte Informações sobre o público-alvo segmentado por lista de clientes.
Não há equivalente. ingested_user_list_info.pair_id_info Não é usado para a Segmentação por lista de clientes.
Não há equivalente. ingested_user_list_info.partner_audience_info Não é usado para a Segmentação por lista de clientes.
logical_user_list Não há equivalente. Não é usado para a Segmentação por lista de clientes.
logical_user_list Não há equivalente. Não é usado para a Segmentação por lista de clientes.
lookalike_user_list Não há equivalente. Não é usado para a Segmentação por lista de clientes.
rule_based_user_list Não há equivalente. Não é usado para a Segmentação por lista de clientes.
similar_user_list Não há equivalente. Não é usado para a Segmentação por lista de clientes.

Informações sobre o público-alvo segmentado por lista de clientes

Na API Google Ads, defina o campo crm_based_user_list como um CrmBasedUserListInfo ao criar um público-alvo segmentado por lista de clientes.

Na API Data Manager, defina os atributos equivalentes definindo o campo ingested_user_list_info como um IngestedUserListInfo e, em seguida, defina os campos obrigatórios para a segmentação por lista de clientes e o tipo de dados do usuário.

Dados de contato

upload_key_types
Definido como uma lista que contém CONTACT_ID. Isso equivale a definir upload_key_type como CONTACT_INFO na API Google Ads.
contact_id_info

Defina como um ContactIdInfo.

Defina data_source_type como DATA_SOURCE_TYPE_FIRST_PARTY. Isso é equivalente a definir data_source_type como FIRST_PARTY na API Google Ads.

IDs de dispositivos móveis

upload_key_types
Definido como uma lista que contém MOBILE_ID. Isso equivale a definir upload_key_type como MOBILE_ADVERTISING_ID na API Google Ads.
mobile_id_info

Defina como um MobileIdInfo.

  • Defina data_source_type como DATA_SOURCE_TYPE_FIRST_PARTY. Isso é equivalente a definir data_source_type como FIRST_PARTY na API Google Ads.
  • Defina key_space para IOS ou ANDROID. A API Data Manager exige esse valor. Isso é diferente da API Google Ads, em que o espaço de chaves é inferido do app_id.
  • Defina app_id como a string que identifica exclusivamente o aplicativo para dispositivos móveis de onde os dados foram coletados. Use o mesmo formato que você usa para o app_id na API Google Ads.

IDs de usuários

upload_key_types
Definido como uma lista que contém USER_ID. Isso equivale a definir upload_key_type como CRM_ID na API Google Ads.
user_id_info

Defina como um UserIdInfo.

Defina data_source_type como DATA_SOURCE_TYPE_FIRST_PARTY. Isso é equivalente a definir data_source_type como FIRST_PARTY na API Google Ads.

Nomes de recursos

A API Data Manager usa um formato de nome de recurso diferente da API Google Ads.

API Google Ads

Na API Google Ads, um nome de recurso UserList usa o formato:

customers/{customer_id}/userLists/{user_list_id}

API Data Manager

Na API Data Manager, um nome de recurso UserList usa o formato:

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

Fazer upload de mapeamentos de campo

Use os mapeamentos nas tabelas para mapear um AddOfflineUserDataJobOperationsRequest na API Google Ads para o equivalente IngestionService na API Data Manager.

Campos de solicitação

Esses mapeamentos usam o IngestAudienceMembersRequest na API Data Manager como referência, mas também podem ser usados se você estiver convertendo sua solicitação da API Google Ads para um RemoveAudienceMembersRequest ou um RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (API Google Ads) IngestAudienceMembersRequest (API Data Manager) Observações
  • Campo customer_id
  • Campo customer_match_user_list_metadata de OfflineUserDataJob
  • 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 público-alvo.
consent do customer_match_user_list_metadata de OfflineUserDataJob consent Configurações de consentimento padrão opcionais para membros do público-alvo na solicitação. É possível substituir esse valor para um membro individual do público-alvo definindo o campo consent de AudienceMember.
Não há equivalente encoding Obrigatório:defina como o Encoding usado para valores de UserIdentifier.
Não há equivalente encryption_info Definido se a solicitação contém valores criptografados. Consulte Criptografia para mais detalhes.
job_id Não há equivalente Use o request_id retornado na resposta para recuperar diagnósticos.
enable_partial_failure Não há equivalente A API Data Manager usa um modelo de erro de falha rápida. Se algum campo de um IngestAudienceMembersRequest falhar na validação, a API Data Manager vai rejeitar toda a solicitação. Recupere erros de processamento usando diagnósticos.
enable_warnings Não há equivalente A API Data Manager não informa avisos na resposta. Recupere avisos de processamento usando diagnostics.
validate_only validate_only
operations audience_members A lista de participantes do público-alvo a serem adicionados ou removidos. Consulte a seção "Campos de operação" para mais detalhes.
Não há equivalente terms_of_service Obrigatório. Definido para indicar que o usuário aceitou ou rejeitou os Termos de Serviço da Segmentação por lista de clientes.

Campos de cliente e público-alvo

A API Google Ads só permite o upload de membros do público-alvo para um público-alvo por trabalho.Além disso, o cabeçalho da solicitação developer-token é obrigatório, e você define os cabeçalhos da solicitação login-customer-id e linked-customer-id para diferentes cenários de autenticação.

A API Data Manager permite enviar membros de vários públicos-alvo em uma única solicitaçã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.

Na API Google Ads, é possível remover todos os membros de um público-alvo definindo o campo remove_all de um OfflineUserDataJobOperation como true.

Na API Data Manager, isso é feito enviando um RemoveAllAudienceMembersRequest. Consulte o guia Remover todos os membros para mais detalhes.

Saiba como mapear os campos da API Google Ads para um único público-alvo com os campos equivalentes em um Destination:

API Google Ads Destination (API Data Manager) Observações
customer_id da solicitação operating_account Defina o account_id como o ID do cliente do público-alvo. 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.
user_list do customer_match_user_list_metadata de OfflineUserDataJob product_destination_id Obrigatório. Definido como o ID numérico do público-alvo. Não use o nome do recurso do UserList.
Não há equivalente reference Um identificador definido pelo usuário para o Destination. Defina esse campo se você estiver enviando membros de vários públicos-alvo em uma única solicitação.

Campos de operação

A API Data Manager contém métodos separados para adicionar e remover membros do público-alvo. Por outro lado, o AddOfflineUserDataJobOperationsRequest na API Google Ads contém uma lista de operations, cada um deles adiciona ou remove um membro ou remove todos os membros com base no tipo de operação. Confira o mapeamento de cada tipo de operação para o método correspondente na API Data Manager:

OfflineUserDataJobOperation (API Google Ads) Método IngestionService (API Data Manager) Observações
create IngestAudienceMembers Consulte a seção Campos de membros do público-alvo para mais detalhes.
remove RemoveAudienceMembers Consulte a seção Campos de membros do público-alvo para mais detalhes.
remove_all RemoveAllAudienceMembers Consulte Remover todos os membros do público-alvo para mais detalhes.

Campos de membros do público-alvo

UserData (API Google Ads) AudienceMember (API Data Manager) Observações
consent consent

Definido para especificar o consentimento do membro do público-alvo.

Ambas as APIs usam um objeto Consent semelhante (ad_user_data, ad_personalization).

Para a API Data Manager, também é possível definir o consentimento de todos os membros do público-alvo em uma solicitação definindo o campo consent no nível da solicitação.
transaction_attribute Não há equivalente. Não aplicável à Segmentação por lista de clientes.
user_attribute Não há equivalente. Não aplicável à Segmentação por lista de clientes.
user_identifiers
  • mobile_data
  • user_id_data
  • composite_data
    • user_data
    • ip_data

Preencha o campo que corresponde ao tipo de dados que você está enviando para os membros do público-alvo. Consulte Campos de identificador do usuário para mais detalhes.

Campos do identificador de usuário

Na API Google Ads, seja enviando informações de contato, IDs de dispositivos móveis ou IDs de usuários, você usa UserIdentifier. A API Data Manager usa uma abordagem diferente, com campos diferentes para cada tipo de dados.

Na API Data Manager, preencha o campo que corresponde ao tipo de dados que você está enviando:

Dados de contato

Se você estiver usando dados de contato, como endereço de e-mail, número de telefone ou endereço, defina composite_data como um CompositeData com uma entrada separada em user_data.user_identifiers para cada item de dados de contato.

Embora user_data ainda tenha suporte, recomendamos usar composite_data para garantir que sua integração esteja preparada para melhorias futuras. Consulte Dados compostos para mais detalhes.

UserIdentifier (API Google Ads) UserIdentifier (API Data Manager) Observações
address_info address Consulte Campos de endereço 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.
user_identifier_source Não há equivalente.

Campos de endereço

Confira os mapeamentos de campo entre OfflineUserAddressInfo na API Google Ads e AddressInfo na API Data Manager. Use esses mapeamentos se você estiver usando informações de contato para preencher seu público-alvo segmentado por lista de clientes.

OfflineUserAddressInfo (API Google Ads) AddressInfo (API Data Manager) Observações
city Não há equivalente.
country_code region_code Obrigatório
hashed_first_name given_name

Obrigatório. Definido como o nome formatado e com hash fornecido. Também é possível criptografar o nome fornecido com hash.
hashed_last_name family_name

Obrigatório. Definido como o nome da família formatado e com hash. Também é possível criptografar o nome da família com hash.
hashed_street_address Não há equivalente.
postal_code postal_code Obrigatório
state Não há equivalente.

Endereço IP

A API Data Manager permite incluir endereços IP para uploads de segmentos de público-alvo por lista de clientes, além de identificadores de usuário. Eles são fornecidos em CompositeData, que agrupa UserData e IpData. Fornecer esses campos juntos pode ajudar a melhorar as taxas de correspondência.

Consulte Ingestão de IP para Segmentação por lista de clientes para mais detalhes.

API Google Ads CompositeData (API Data Manager) Observações
Não há equivalente. ip_data.ip_address Definido como o endereço IPv4 ou IPv6 bruto. Consulte as orientações sobre o formato de endereço IP.
Não há equivalente. ip_data.observe_start_time Definido como o carimbo de data/hora no formato RFC 3339 quando o endereço IP foi observado pela primeira vez.
Não há equivalente. ip_data.observe_end_time Definido como o carimbo de data/hora no formato RFC 3339 quando o endereço IP foi observado pela última vez.
user_identifiers user_data Definido como um objeto UserData.

IDs de dispositivos móveis

Se você estiver usando IDs de dispositivos móveis, defina mobile_data como um MobileData com uma entrada em mobile_ids para cada ID.

UserIdentifier (API Google Ads) MobileData (API Data Manager) Observações
mobile_id mobile_ids Definido como a lista de IDs de dispositivos móveis do membro do público-alvo.

Na API Google Ads, você adiciona um UserIdentifier com mobile_id para cada ID de dispositivo móvel do membro do público-alvo. Na API Data Manager, adicione um MobileData único com mobile_ids definido como a lista de todos os IDs de dispositivos móveis do membro do público-alvo.

user_identifier_source Não há equivalente.

IDs de usuários

Se você estiver usando IDs de usuário, defina user_id_data como um UserIdData e defina user_id como o ID do usuário para o membro do público-alvo.

UserIdentifier (API Google Ads) UserIdData (API Data Manager) Observações
third_party_user_id user_id

Na API Google Ads, você adiciona um UserIdentifier third_party_user_id separado para cada ID de usuário do membro do público-alvo.

Na API Data Manager, defina o campo user_id_data como um UserIdData e o campo user_id como o ID do usuário do membro do público-alvo. Não é possível enviar vários IDs de usuário para o mesmo membro do público-alvo.

user_identifier_source Não há equivalente.
Anterior
Etapas para o upgrade