Enviar membros do público-alvo

Você pode seguir este guia de início rápido para se familiarizar com a API Data Manager. Escolha a versão do início rápido que você quer ver:

Neste guia de início rápido, você vai concluir as seguintes etapas:

Prepare um Destination para receber dados de público-alvo.
Prepare os dados de público-alvo para envio.
Crie uma solicitação IngestionService para membros do público-alvo.
Envie a solicitação com o Google APIs Explorer.
Entenda as respostas de sucesso e falha.

Preparar um destino

Antes de enviar dados, é preciso preparar o destino para onde eles serão enviados. Confira um exemplo de Destination para usar. Confira Configurar destinos para exemplos de destinos em diferentes cenários.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

Defina o operatingAccount como o tipo e o ID da conta que vai receber os dados de público-alvo.
Se as credenciais do OAuth forem de um usuário com acesso a uma conta de administrador do Google Ads que tenha operatingAccount como uma das subcontas, defina loginAccount como o tipo de conta e o ID da conta de administrador.
Se as credenciais do OAuth forem de um usuário com acesso direto ao operatingAccount, não será necessário definir loginAccount.

Preparar os dados de público-alvo

Considere os seguintes dados de exemplo em um arquivo separado por vírgulas. Cada linha do arquivo corresponde a um membro do público-alvo, e cada membro tem até três endereços de e-mail.

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

Os endereços de e-mail têm os seguintes requisitos de formatação e hash:

Remova todos os espaços em branco à esquerda, à direita e intermediários.
Converta o endereço de e-mail em letras minúsculas.
Criptografe o endereço de e-mail com hash usando o algoritmo SHA-256.
Codifique os bytes de hash usando hexadecimal (hex) ou codificação Base64. Os exemplos neste guia usam codificação hexadecimal.

Estes são os dados formatados:

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

Estes são os dados depois de serem criptografados com hash e codificados:

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

Confira um exemplo de AudienceMember para os endereços de e-mail formatados, com hash e codificados de dana@example.com e danam@example.com da primeira linha dos dados de entrada:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

Criar o corpo da solicitação

Para criar o corpo da solicitação, combine destinations e audienceMembers, defina o campo encoding e adicione outros campos que você quer incluir, como validateOnly e consent.

Se você estiver enviando membros do público-alvo para a Segmentação por lista de clientes, defina termsOfService para indicar se o usuário aceitou os Termos de Serviço da Segmentação por lista de clientes.

Os exemplos neste guia não usam criptografia, mas você pode seguir as instruções em Criptografar dados do usuário para adicionar criptografia ao seu processo.

Enviar a solicitação

Clique em Abrir no APIs Explorer para abrir o APIs Explorer em uma nova guia ou janela.
No corpo da solicitação no API Explorer, substitua cada string que começa com REPLACE_WITH, como REPLACE_WITH_OPERATING_ACCOUNT_TYPE, pelo valor relevante.
Clique em Executar na parte de baixo da página do API Explorer e conclua os prompts de autorização para enviar a solicitação.
Defina validateOnly como true para validar a solicitação sem aplicar as mudanças. Quando estiver tudo pronto para aplicar as mudanças, defina validateOnly como false.

Solicitação de ingestão

Abrir no API Explorer

{
    "destinations": [
        {
            "operatingAccount": {
                "accountType": "OPERATING_ACCOUNT_TYPE",
                "accountId": "OPERATING_ACCOUNT_ID"
            },
            "loginAccount": {
                "accountType": "LOGIN_ACCOUNT_TYPE",
                "accountId": "LOGIN_ACCOUNT_ID"
            },
            "productDestinationId": "AUDIENCE_ID"
        }
    ],
    "audienceMembers": [
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
                    },
                    {
                        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
                    },
                    {
                        "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
                    },
                    {
                        "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
                    },
                    {
                        "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
                    },
                    {
                        "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
                    }
                ]
            }
        }
    ],
    "consent": {
        "adUserData": "CONSENT_GRANTED",
        "adPersonalization": "CONSENT_GRANTED"
    },
    "encoding": "HEX",
    "termsOfService": {
        "customerMatchTermsOfServiceStatus": "ACCEPTED"
    },
    "validateOnly": true
}

Respostas de sucesso

Uma solicitação bem-sucedida retorna uma resposta com um objeto que contém um requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Registre o requestId retornado para que você possa recuperar diagnósticos à medida que cada destino na solicitação é processado.

Respostas de falha

Uma solicitação com falha resulta em um código de status de resposta de erro, como 400 Bad Request, e uma resposta com detalhes do erro.

Por exemplo, um emailAddress que contém uma string de texto simples em vez de um valor codificado em hexadecimal produz a seguinte resposta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Um emailAddress não criptografado e codificado apenas em hexadecimal produz a seguinte resposta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Enviar eventos para vários destinos

Se os dados tiverem membros do público-alvo para destinos diferentes, é possível enviá-los na mesma solicitação usando referências de destino.

Por exemplo, se você tiver um membro do público-alvo para o ID da lista de usuários 11112222 e outro para o ID 77778888, envie os dois em uma única solicitação definindo o reference de cada Destination. O reference é definido pelo usuário. O único requisito é que cada Destination tenha um reference exclusivo. Esta é a lista destinations modificada para a solicitação:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

Defina o destination_references de cada AudienceMember para enviar a um ou mais destinos específicos. Por exemplo, aqui está um AudienceMember que é apenas para o primeiro Destination. Portanto, a lista destination_references contém apenas o reference do primeiro Destination:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

O campo destination_references é uma lista. Portanto, é possível especificar vários destinos para um membro do público-alvo. Se você não definir o destination_references de um AudienceMember, a API Data Manager vai enviar o membro do público-alvo para todos os destinos na solicitação.

Próximas etapas

Configure a autenticação e configure seu ambiente com uma biblioteca de cliente.
Saiba mais sobre os requisitos de formatação, hash e codificação para cada tipo de dado.
Saiba como criptografar dados de usuários.
Saiba como recuperar diagnósticos para suas solicitações.
Saiba mais sobre as práticas recomendadas.
Saiba mais sobre limites e cotas.

Visão geral do público-alvo