Esta página foi traduzida pela API Cloud Translation.

Como começar

Recomendamos usar a biblioteca de cliente com o Apache Maven (ou Gradle).

Criar um novo projeto Maven/Gradle

Crie um novo projeto Maven/Gradle no ambiente de desenvolvimento integrado de sua escolha. Nossos artefatos são publicados no repositório central do Maven (em inglês).

A dependência do Maven é:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>29.0.0</version>
</dependency>

A dependência do Gradle é:

implementation 'com.google.api-ads:google-ads:29.0.0'

Você também pode criar a partir da origem. Neste guia, presume-se que você tenha uma configuração de projeto com as dependências necessárias disponíveis.

Receber credenciais para autenticar com a API

O acesso à API Google Ads requer credenciais do OAuth e um token de desenvolvedor da API Google Ads. Esta seção explica o que são, como são usados e como são recebidos.

Token de desenvolvedor (para acesso à API)

O token de desenvolvedor está vinculado a uma conta de administrador e pode ser encontrado na interface da Web do Google Ads.

Embora o token de desenvolvedor esteja vinculado a uma conta de administrador, ele não fornece acesso a ela. Em vez disso, o token de desenvolvedor concede acesso à API em geral, e o acesso no nível da conta é configurado por meio do OAuth.

Credenciais OAuth (para acesso a contas do Google Ads)

Para autorizar o acesso de usuários da Conta do Google às contas do Google Ads, forneça um conjunto de credenciais do OAuth.

Existem dois fluxos de OAuth que geralmente são usados: app para computador (instalado) ou app da Web. A principal diferença entre os dois é que os apps para computador precisam abrir o navegador do sistema e fornecer um URI de redirecionamento local para lidar com respostas do servidor de autorização do Google, enquanto os apps da Web podem redirecionar um navegador de terceiros arbitrário para concluir a autorização e enviar as credenciais de volta ao seu servidor. A biblioteca também oferece suporte ao fluxo de conta de serviço menos usado.

Se você autorizar o uso das suas próprias credenciais (fluxo do app para computador): Consulte o Fluxo de apps para computador do OAuth. Isso inclui todos os detalhes necessários para autorizar com suas próprias credenciais.
Se você autorizar como um usuário terceirizado do Google (fluxo da Web): Consulte o fluxo de app da Web OAuth. Isso dá um exemplo de como configurar a autorização OAuth para usuários de terceiros arbitrários.
Se você autorizar como um usuário do domínio do Google Apps (fluxo de conta de serviço): Consulte o fluxo de contas de serviço do OAuth. Este exemplo mostra como configurar a autorização OAuth para usuários do domínio do Google Apps.

Se você acessa a conta de cliente do Google Ads por meio de uma conta de administrador do Google Ads, também é necessário especificar um ID de cliente de login, conforme descrito abaixo.

ID de cliente de login (para acesso às contas do Google Ads com uma conta de administrador)

Se quiser, especifique o ID de cliente de uma conta de administrador que concede acesso à conta de veiculação. Isso precisa ser especificado se você acessa a conta do cliente por uma conta de administrador. Não é necessário especificar todas as contas de administrador no caminho para o ID de cliente, apenas o ID de administrador superior que você está usando para as permissões de acesso. Para mais detalhes, consulte a documentação relacionada.

Configurar a biblioteca de cliente com suas credenciais

Configure a biblioteca de cliente com um arquivo de configuração, variáveis de ambiente ou de maneira programática. Neste guia, vamos usar a abordagem do arquivo de configuração e focar os fluxos para computador e Web. Usar um arquivo de configuração geralmente é uma boa abordagem quando você tem apenas um conjunto de credenciais (por exemplo, se você gerencia contas em um único administrador).

Crie um arquivo ~/ads.properties com o seguinte conteúdo.

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Substitua os marcadores de posição pelas suas credenciais recebidas na etapa anterior.

Além disso, se o token de atualização for de uma conta de administrador, especifique o ID de cliente dessa conta como o cliente de login:

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Valide as credenciais

Para garantir que tudo esteja configurado corretamente, vamos executar o exemplo GetCampaigns.

Primeiro, navegue até o diretório google-ads-examples.

$ cd google-ads-examples

Este exemplo requer um parâmetro --customerId, em que o valor é o ID de cliente da sua conta do Google Ads sem traços.

Para executar com o Gradle:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

Confira outros exemplos

O pacote de exemplos (link em inglês) em google-ads-examples contém vários exemplos úteis. A maioria dos exemplos exige parâmetros. É possível transmitir os parâmetros como argumentos (recomendado) ou editar os valores de INSERT_XXXXX_HERE no código-fonte. Para consultar uma instrução de uso de um exemplo, transmita --help como o único argumento.

Com o Gradle:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --help"

Também é possível usar a tarefa listExamples no Gradle para listar todos os exemplos, exemplos em um subdiretório ou exemplos em que a descrição inclui um termo de pesquisa.

# List all examples:
$ ./gradlew -q listExamples
# List examples in the 'basicoperations' subdirectory:
$ ./gradlew -q listExamples --subdirectory='basicoperations'
# Search for examples where the description includes 'Performance Max':
$ ./gradlew -q listExamples --searchTerm='Performance Max'