Esta página foi traduzida pela API Cloud Translation.

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 seu 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.

Entenda o modelo de acesso do Google Ads

Para trabalhar de maneira eficaz com a API Google Ads, é importante entender como funciona o modelo de acesso do Google Ads. Recomendamos que você leia o guia do modelo de acesso do Google Ads.

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.

Saiba como configurar o OAuth2 para acesso à API usando suas próprias credenciais com uma conta de serviço na biblioteca de cliente Perl:

Crie credenciais do OAuth2:

Siga as instruções para gerar uma conta de serviço e um arquivo *.JSON.
Configure a biblioteca de cliente:

Defina o caminho JSON da chave privada na sua configuração. Se você estiver usando um arquivo googleads.properties, adicione o seguinte:
```
jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
```
Se você estiver usando variáveis de ambiente, adicione o seguinte à sua configuração ou ambiente do Bash:
```
export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH
```
Ponto-chave: ao carregar configurações, a biblioteca primeiro procura credenciais dos fluxos de apps da Web ou de computador OAuth2 e as usa se forem encontradas. Portanto, se você quiser usar uma conta de serviço para autenticação, verifique se as credenciais dos outros fluxos não estão presentes na sua configuração.

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:

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 acesso a uma conta de administrador da API Google Ads e vincular todas as contas do Google Ads a ela.
O usuário executa o exemplo de código generate_user_credentials.pl para autorizar seu app a gerenciar todas as contas do Google Ads em nome dele.

As etapas a seguir executam um exemplo de código interativo, que exige que você forneça entrada.

Em um terminal, execute o exemplo generate_user_credentials.pl no diretório examples. Você pode modificar os valores INSERT_XXX_HERE no exemplo antes de executar ou usar os argumentos de linha de comando -client_id para ID do cliente e -client_secret para chave secreta do cliente.
```
perl generate_user_credentials.pl -client_id {client_id} -client_secret {client_secret}
```
Este exemplo de código pede que você acesse um URL em que precisa autorizar o app a acessar sua conta do Google Ads em seu nome.
```
Paste this url in your browser:
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=...
```
Acesse o URL em uma sessão de navegação privada ou em uma janela anônima. Faça login com a Conta do Google que você usa para acessar o Google Ads. Normalmente, é uma conta de e-mail com acesso a uma conta de administrador do Google Ads que contém todas as contas que você precisa gerenciar na hierarquia dela. Clique em Continuar na tela de permissão do OAuth 2.0.

Você vai ser redirecionado para uma página com uma mensagem indicando que a autorização foi concluída.
```
Authorization code was successfully retrieved.
```
Volte para o console em que você está executando o exemplo de código. Você vai notar que o exemplo de código foi concluído e está mostrando seu token de atualização e algumas instruções, seguidas pelas instruções que você precisa seguir para configurar a biblioteca de cliente:
```
Replace the following keys and values in your googleads.properties configuration file:

clientId==***********************apps.googleusercontent.com
clientSecret=****
refreshToken=****
```
Pressione Ctrl + C para encerrar o processo. Em seguida, copie o token de atualização gerado junto com o ID e a chave secreta do cliente no arquivo googleads.properties ou salve em outro lugar para usar ao instanciar a biblioteca em tempo de execução.

A biblioteca pode ser inicializada usando as credenciais OAuth 2.0 do usuário ao definir o seguinte em googleads.properties:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Outra opção é usar variáveis de ambiente:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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. Seu app cria e gerencia as credenciais de usuário do OAuth 2.0.

Em Perl, normalmente você implementa um fluxo de aplicativo da Web em que seu aplicativo processa o redirecionamento do OAuth 2.0 e o gerenciamento de tokens. O usuário se autentica pelo aplicativo, que armazena e usa o token de atualização do usuário para fazer chamadas de API em nome dele.

A configuração para usar as credenciais obtidas é a mesma do fluxo de autenticação de usuário único:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Outra opção é usar variáveis de ambiente:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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 Perl fornece exemplos que ilustram como lidar com esses casos.

O exemplo get_account_hierarchy.pl mostra como recuperar a lista de todas as contas em uma conta de administrador do Google Ads.
O exemplo list_accessible_customers.pl 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 no arquivo googleads.properties ou na variável de ambiente GOOGLE_ADS_LOGIN_CUSTOMER_ID.