Autenticação e autorização

Assim como outras APIs do Google, a API Google Ads usa o protocolo OAuth 2.0 para autenticação e autorização. O OAuth 2.0 permite que o app cliente da API Google Ads acesse a conta do Google Ads de um usuário sem precisar processar ou armazenar as informações de login dele.

Este guia aborda como configurar a biblioteca de cliente Java para autenticação da API Google Ads usando os três fluxos do OAuth 2.0 mais comuns, além de explicar as credenciais necessárias.

Para mais detalhes sobre o modelo de acesso da API Google Ads, leia o guia do modelo de acesso do Google Ads.

Credenciais

O acesso à API Google Ads exige um token de desenvolvedor, credenciais do OAuth 2.0 e, em alguns casos, um ID de cliente de login.

Token de desenvolvedor

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 dá acesso a ela. Em vez disso, o token de desenvolvedor concede acesso à API em geral, e o acesso no nível da conta é configurado pelo OAuth 2.0.

Na biblioteca de cliente, o token de desenvolvedor é especificado pela chave api.googleads.developerToken no arquivo ads.properties.

Credenciais do OAuth 2.0

Para autorizar como usuários da Conta do Google com acesso a contas do Google Ads, você precisa fornecer um conjunto de credenciais do OAuth 2.0. O tipo de credenciais necessárias varia de acordo com o fluxo do OAuth 2.0 usado.

A biblioteca é compatível com três fluxos:

  • Fluxo da conta de serviço
  • Fluxo de autenticação de usuário único
  • Fluxo de autenticação multiusuário

Consulte a visão geral do OAuth para detalhes sobre os fluxos do OAuth da API Google Ads e siga as instruções do fluxo que melhor atende às suas necessidades para receber as credenciais necessárias.

ID de cliente de login

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

Na biblioteca de cliente, o ID do cliente de login é especificado pela chave api.googleads.loginCustomerId no arquivo ads.properties.

Configuração

É possível configurar a biblioteca de cliente com um arquivo ads.properties, variáveis de ambiente ou de maneira programática. Este guia se concentra no uso de um arquivo ads.properties. Consulte o guia de configuração para detalhes sobre todas as opções.

Se você estiver usando um arquivo ads.properties, coloque-o no diretório principal: ~/ads.properties.

Fluxos de trabalho do OAuth

Há três fluxos de trabalho comuns usados ao trabalhar com a API Google Ads.

Fluxo da conta de serviço

Esse é o fluxo de trabalho recomendado se o seu não exigir interação humana. Esse fluxo de trabalho exige uma etapa de configuração em que o usuário adiciona uma conta de serviço à conta do Google Ads. Em seguida, o app pode usar as credenciais da conta de serviço para gerenciar a conta do Google Ads do usuário.

Depois de ter o arquivo JSON da chave privada, adicione o seguinte ao arquivo ads.properties:

api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

Consulte o guia de fluxo de trabalho da conta de serviço para saber mais.

Fluxo de autenticação de usuário único

Esse fluxo de trabalho pode ser usado se você não puder usar contas de serviço. Esse fluxo de trabalho exige duas etapas de configuração:

  1. Conceda a um único usuário acesso a todas as contas que serão gerenciadas usando a API Google Ads. Uma abordagem comum é dar ao usuário uma conta de administrador da API Google Ads e vincular todas as contas do Google Ads a ela.
  2. O usuário executa uma ferramenta de linha de comando, como gcloud ou o exemplo de código GenerateUserCredentials para autorizar seu app a gerenciar todas as contas do Google Ads em nome dele.

Depois de ter essas credenciais, adicione o seguinte ao arquivo ads.properties:

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

Consulte o guia do fluxo de trabalho de autenticação de usuário único para saber mais.

Fluxo de autenticação multiusuário

Esse é o fluxo de trabalho recomendado se o app permitir que os usuários façam login e autorizem o app a gerenciar as contas do Google Ads em nome deles. O GenerateUserCredentials é um exemplo de código de linha de comando que ilustra como obter a autenticação do usuário em tempo de execução para gerenciar as contas do Google Ads em nome dele. Use este exemplo de código como referência para criar apps de computador que exigem autenticação do usuário.

Adicione a instrução a seguir ao seu arquivo ads.properties:

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

Consulte o guia do fluxo de trabalho de autenticação multiusuário para saber mais.

E se meu usuário gerenciar várias contas?

É comum um usuário gerenciar mais de uma conta do Google Ads, seja por acesso direto a elas ou por uma conta de administrador do Google Ads. A biblioteca de cliente Java fornece os exemplos de código a seguir que ilustram como lidar com esses casos.

  1. O exemplo de código GetAccountHierarchy mostra como recuperar a lista de todas as contas em uma conta de administrador do Google Ads.
  2. O exemplo de código ListAccessibleCustomers mostra como recuperar a lista de todas as contas a que um usuário tem acesso direto. Essas contas podem ser usadas como valores válidos para a configuração LoginCustomerId.

Application Default Credentials

A biblioteca de cliente Java também aceita autenticação com credenciais padrão do aplicativo.

Isso é particularmente útil para desenvolvimento local ou com diferentes APIs do Google, já que é possível reutilizar as mesmas credenciais, desde que elas acessem os escopos corretos do OAuth 2.0.

Para a API Google Ads, verifique se as credenciais padrão do aplicativo podem acessar o escopo https://www.googleapis.com/auth/adwords do OAuth 2.0.

Para usar as credenciais padrão do aplicativo, defina a opção api.googleads.useApplicationDefaultCredentials como true no arquivo ads.properties. Ao usar as credenciais padrão do aplicativo, o ID do cliente, a chave secreta do cliente e o token de atualização não devem ser definidos.