The Data Manager API is in closed beta. To express interest in joining the closed beta, fill out this form.

Esta página foi traduzida pela API Cloud Translation.

Configurar o acesso à API

Confira como configurar o acesso à API Data Manager com um SDK ou REST.

Pré-requisitos

Antes de usar a API Data, verifique se você tem o seguinte:

Um projeto do Google Cloud.
Uma Conta do Google que atenda aos dois critérios a seguir:
1. Recebeu acesso à API Data Manager depois de preencher o formulário de interesse na API Data Manager. Se você conseguir acessar a página Detalhes do produto de API, você tem acesso.
2. Tem a permissão serviceusage.services.enable no seu projeto do Google Cloud ou um papel que inclui essa permissão. Por exemplo, roles/owner e roles/serviceusage.serviceUsageAdmin incluem a permissão serviceusage.services.enable. Para verificar suas permissões, consulte Ver acesso atual.

Ativar a API

Se você ainda não fez isso, clique em Ativar a API Data Manager ou siga as instruções para realizar essa etapa manualmente.

Se você não encontrar a API Data Manager ou se a opção Ativar a API Data Manager falhar, verifique se sua Conta do Google atende aos pré-requisitos.

Configurar a autenticação

Você pode usar qualquer um dos métodos de autenticação no Google, além das chaves de API. Recomendamos que você consulte Escolher o método de autenticação certo para seu caso de uso e decida qual abordagem é adequada para você.

Dois métodos de autenticação comuns são contas de usuário e contas de serviço:

Contas de usuário: representam pessoas que interagem diretamente com as APIs e os serviços do Google.
Contas de serviço: representam apps, não pessoas, como usuários. Elas permitem que seus apps gerenciem a autenticação e a autorização. Por exemplo, se um app precisa acessar recursos do Google Cloud.

Sua integração pode usar o Application Default Credentials (ADC) para encontrar automaticamente as credenciais do ambiente. Assim, não é necessário mudar o código do cliente para autenticar.

Escolha Conta de usuário ou Representação de conta de serviço para configurar o ADC:

Estas são as etapas para autenticar com credenciais da conta de usuário:

Configure as configurações da plataforma de autenticação do Google para seu projeto.

Importante: qualquer app do Google Cloud usado para receber credenciais de usuário para o escopo da API Data Manager precisa passar pela verificação do Google OAuth para evitar uma tela de interface não verificada para os usuários. A verificação do OAuth do Google não é necessária para contas de serviço.
1. Abra a página de branding no console do Google Cloud.
2. Selecione o projeto.
3. Preencha o formulário e clique em Criar.
Como o escopo da API Data Manager é sensível, as seguintes etapas são necessárias:
1. Acesse as configurações de Acesso a dados do seu projeto.
2. Clique em Adicionar ou remover escopos.
3. Marque a caixa ao lado de API Data Manager na lista de escopos e clique em Atualizar.
4. Clique em Salvar.
5. Acesse Público-alvo no console do Google Cloud e atualize o Status de publicação e o Tipo de usuário. Saiba mais sobre essas configurações em Gerenciar público-alvo do app.
Clique em Criar cliente OAuth2 para criar um cliente OAuth2 no projeto ou siga as instruções para criar um cliente OAuth2 para computador.

Criar cliente OAuth2
Na última etapa, clique em FAZER O DOWNLOAD DA CONFIGURAÇÃO DO CLIENTE e anote o local de download escolhido.
Gere um arquivo ADC local executando o seguinte comando. Esse comando inicia um fluxo da Web em que você precisa fazer login na Conta do Google que está usando com a API.

Substitua PATH_TO_CLIENT_JSON pelo nome do arquivo JSON que você baixou.
```
gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file="PATH_TO_CLIENT_JSON"
```
Confirme se as credenciais estão configuradas corretamente usando o seguinte comando. Se a operação for bem-sucedida, o comando vai imprimir um token de acesso no console.
```
gcloud auth application-default print-access-token
```

Para saber mais sobre autenticação e credenciais do seu app, consulte Métodos de autenticação no Google e Como as credenciais padrão do aplicativo funcionam.

Configurar o acesso à conta operacional

Conceda ao e-mail associado à sua conta de usuário acesso ao Destination.

Se você estiver usando uma conta do Google Ads ou de parceiro de dados, siga as instruções para adicionar o e-mail do usuário à conta.
Se você estiver usando uma conta do Display & Video 360, siga as instruções para adicionar o e-mail do usuário à conta.

Configurar o SDK para sua linguagem de programação

Na máquina local, instale o SDK de sua escolha:

REST

Atualize os marcadores no exemplo a seguir, como OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID e AUDIENCE_ID, com os valores da sua conta e destino.
Substitua PROJECT_ID pelo ID do Google Cloud.

Copie o exemplo para a linha de comando e envie a solicitação.

Remova o atributo linkedAccount da entrada em destinations se você não estiver acessando operatingAccount usando um link de produto estabelecido.

#!/bin/bash

# Uses gcloud to get an access token. If the Application Default
# Credentials aren't for a service account, the command that specifies
# --scopes fails. This sample falls back to the command without the
# --scopes argument.
DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager || \
  gcloud auth application-default print-access-token)"

# Fetches and prints the scope information for the access token. If you
# get scope-related errors when you send the request in the next step,
# verify that this output includes the Data Manager API scope:
#   https://www.googleapis.com/auth/datamanager
curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token="${DATA_MANAGER_ACCESS_TOKEN}"

# Sends the request.
curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
  --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
  --header "x-goog-user-project: PROJECT_ID" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "destinations": [
    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "product": "LOGIN_ACCOUNT_PRODUCT",
        "accountId": "LOGIN_ACCOUNT_ID"
      },
      "linkedAccount": {
        "product": "LINKED_ACCOUNT_PRODUCT",
        "accountId": "LINKED_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
}
EOF

.NET

Faça o download e extraia google-cloud-ads-datamanager-v1-csharp.tar.gz.
No projeto .NET, declare uma dependência ProjectReference na biblioteca da API Data Manager. Substitua PATH_TO_CLIENT_LIBRARY pelo local em que você extraiu o diretório google-cloud-ads-datamanager-v1-csharp de google-cloud-ads-datamanager-v1-csharp.tar.gz.
```
<ProjectReference Include="PATH_TO_CLIENT_LIBRARY\Google.Ads.DataManager.V1\Google.Ads.DataManager.V1.csproj" />
```
Opcional. Acesse a biblioteca de utilitários e os exemplos de código.
1. Faça o download e extraia data-manager-dotnet.tar.gz.
2. No seu projeto .NET, declare uma dependência ProjectReference na biblioteca de utilitários. Substitua PATH_TO_UTILITY_LIBRARY pelo local em que você extraiu o diretório data-manager-dotnet de data-manager-dotnet.tar.gz.
```
<ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />
```
3. Para formatar dados, use o utilitário Formatter no seu projeto do .NET.
4. Procure exemplos de código no subdiretório samples.
  
  Para executar os exemplos de código, defina a variável de ambiente DATA_MANAGER_DOTNET_LIB como o local em que você extraiu o diretório google-cloud-ads-datamanager-v1-csharp de google-cloud-ads-datamanager-v1-csharp.tar.gz.
```
export DATA_MANAGER_DOTNET_LIB="PATH_TO_CLIENT_LIBRARY"
```
  Mude para o diretório samples e use dotnet run para receber a lista de exemplos disponíveis.
```
dotnet run --framework net8.0
```
  Transmita o argumento --help ao executar uma amostra para imprimir uma instrução de uso com os parâmetros esperados.
```
dotnet run --framework net8.0 -- ingest-audience-members --help
```
  Para começar com alguns dados de amostra, use o arquivo em samples/sampledata/audience_members_1.csv.

Java

Faça o download e extraia google-cloud-ads-datamanager-v1-java.tar.gz.
Navegue até o diretório google-cloud-ads-datamanager-v1-java.
Execute o comando a seguir para criar e publicar a biblioteca no seu repositório Maven local para uso com Maven ou Gradle.
```
./gradlew -Pversion=0.1.0 install
```

No seu projeto Java, declare uma dependência na biblioteca da API Data Manager.

Gradle:

implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.0'

Maven:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
  <version>0.1.0</version>
</dependency>

Opcional. Acesse a biblioteca de utilitários e os exemplos de código.
1. Clone o repositório do GitHub.
```
git clone https://github.com/googleads/data-manager-java.git
```
2. Navegue até o diretório data-manager-java.
3. Crie e publique a biblioteca de utilitários no seu repositório Maven local.
```
./gradlew data-manager-util:install
```
4. No seu projeto Java, declare uma dependência na biblioteca de utilitários.
  
  Gradle:
```
implementation 'com.google.api-ads:data-manager-util:0.1.0'
```
  Maven:
```
<dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>0.1.0</version>
</dependency>
```
5. Para formatar e criptografar os dados, use os utilitários UserDataFormatter e Encrypter no seu projeto Java.
6. Procure exemplos de código no subdiretório data-manager-samples ou no GitHub. Para executar uma amostra na linha de comando, use a tarefa run do Gradle.
  
  Por exemplo, o comando a seguir executa a amostra IngestAudienceMembers e imprime uma declaração de uso:
```
./gradlew data-manager-samples:run \
  --args='IngestAudienceMembers --help'
```
  Para começar com alguns dados de amostra, use o arquivo em data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Python

Faça o download de ads-datamanager-v1-py.tar.gz.
Navegue até o diretório do download.
Execute o comando a seguir para criar a biblioteca e disponibilizá-la a outros projetos no mesmo ambiente Python:
```
pip install ./ads-datamanager-v1-py.tar.gz
```
No seu projeto Python, declare uma dependência na biblioteca da API Data Manager. Por exemplo, se você estiver usando um arquivo requirements.txt no seu projeto, adicione a seguinte linha ao arquivo:
```
google-ads-data-manager=0.1.0
```
Opcional. Acesse a biblioteca de utilitários e os exemplos de código.
1. Faça o download e extraia data-manager-python.tar.gz.
2. Navegue até o diretório data-manager-python.
3. Para instalar a biblioteca de utilitários no seu ambiente Python, execute o seguinte comando:
```
pip install .
```
4. No seu projeto Python, declare uma dependência na biblioteca de utilitários. Por exemplo, se você estiver usando um arquivo requirements.txt no seu projeto, adicione a seguinte linha ao arquivo:
```
google-ads-data-manager-util=0.1.0
```
5. Para formatar e criptografar os dados, use os utilitários Formatter e Encrypter no seu projeto Python.
6. Procure exemplos de código no subdiretório samples. Transmita o argumento --help ao executar uma amostra para imprimir uma instrução de uso com os parâmetros esperados.
  
  Para começar com alguns dados de amostra, use o arquivo em samples/sampledata/audience_members_1.csv.

Node.js

Baixe e extraia ads-datamanager-v1-nodejs.tar.gz.
Navegue até o diretório ads-datamanager-v1-nodejs.
Execute os comandos a seguir para compilar e empacotar a biblioteca em um arquivo .tgz para uso com npm.
```
npm install
npm pack
```
Os comandos geram um arquivo chamado google-cloud-datamanager-0.1.0.tgz.
No seu projeto Node.js, declare uma dependência na biblioteca da API Data Manager adicionando uma entrada dependencies para o caminho completo e o nome do arquivo do arquivo google-cloud-datamanager-0.1.0.tgz.

PHP

Faça o download e extraia google-cloud-ads-datamanager-v1-php.tar.gz.
Navegue até o diretório google-cloud-ads-datamanager-v1-php.
Execute o comando a seguir para resolver as dependências da biblioteca:
```
composer update --prefer-dist
```
No arquivo composer.json do projeto PHP no mesmo host, declare uma dependência na biblioteca da API Data Manager seguindo estas etapas:
1. Adicione uma seção repositories que aponta para o local do diretório google-cloud-ads-datamanager-v1-php.
```
"repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_CLIENT_LIBRARY"
   }
]
```
2. Declare uma dependência na biblioteca da API Data Manager.
```
"require": {
   "googleads/data-manager": "^0.1.0"
}
```
(Opcional) Acesse a biblioteca de utilitários e os exemplos de código.
1. Faça o download e extraia data-manager-php.tar.gz.
2. Navegue até o diretório data-manager-php.
3. Execute o comando a seguir para resolver as dependências da biblioteca:
```
composer update --prefer-dist
```
4. No arquivo composer.json do projeto PHP no mesmo host, declare uma dependência na biblioteca de utilitários seguindo estas etapas:
  1. Adicione uma entrada na seção repositories que aponte para o local do diretório data-manager-php.
```
"repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_UTILITY_LIBRARY"
   }
]
```
  2. Declare uma dependência na biblioteca de utilitários.
```
"require": {
   "googleads/data-manager-util": "@dev"
}
```
  Para formatar dados, use a utilidade Formatter no projeto PHP.
5. Procure exemplos de código no subdiretório samples. Execute as amostras seguindo estas etapas:
  1. Navegue até o diretório samples.
  2. Defina a variável de ambiente DATA_MANAGER_PHP_LIB para o caminho onde você extraiu a biblioteca de cliente.
```
export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"
```
  3. Execute o comando a seguir para resolver as dependências da biblioteca:
```
composer update --prefer-dist
```
  4. Execute as amostras, transmitindo os argumentos necessários. Transmita o argumento --help ao executar uma amostra para imprimir uma declaração de uso com os parâmetros esperados.
  Para começar com alguns dados de amostra, use o arquivo em samples/sampledata/audience_members_1.csv.

Próximas etapas

Saiba mais sobre como enviar dados de público-alvo.
Saiba mais sobre como enviar eventos.
Consulte a documentação de referência REST ou RPC.