O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Autenticação e autorização

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.

Entender o modelo de acesso do Google Ads

Para trabalhar de forma eficaz com a API Google Ads, entenda como funciona o modelo de acesso do Google Ads. Consulte 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 fluxo de trabalho não exigir nenhuma interação humana. Esse fluxo de trabalho requer uma etapa de configuração, em que o usuário adiciona uma conta de serviço à conta do Google Ads. O app pode usar as credenciais da conta de serviço para gerenciar a conta do Google Ads do usuário.

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

Crie credenciais do OAuth2:

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

Defina o caminho JSON da chave privada (e o impersonatedEmail opcional se estiver usando a delegação em todo o domínio do Google Workspace) na configuração. Se você estiver usando um arquivo googleads.properties, adicione o seguinte:
```
jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
# Optional unless using Google Workspace domain-wide delegation:
impersonatedEmail=IMPERSONATED_EMAIL
loginCustomerId=LOGIN_CUSTOMER_ID
```
Se você estiver usando variáveis de ambiente, adicione o seguinte à configuração ou ao ambiente do Bash:
```
export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=\
IMPERSONATED_EMAIL
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID
```
Importante : ao carregar configurações, a biblioteca primeiro procura credenciais dos fluxos de apps da Web ou para computador do OAuth2 e as usa, se encontradas. 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 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 requer duas etapas de configuração:

Dê 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 essa conta de administrador.
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 uma entrada.

Em um terminal, execute o exemplo generate_user_credentials.pl no diretório examples. É possível modificar os valores de INSERT_XXX_HERE no exemplo antes de executar ou usar os argumentos de linha de comando -client_id para o ID do cliente e -client_secret para a chave secreta do cliente.
```
perl generate_user_credentials.pl \
  -client_id OAUTH_CLIENT_ID \
  -client_secret OAUTH_CLIENT_SECRET
```
Este exemplo de código solicita que você acesse um URL para 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...
```
Acesse o URL em uma sessão de navegador 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 que tem acesso a uma conta de administrador do Google Ads que contém todas as contas que você precisa gerenciar na hierarquia de contas. Clique em Continuar na tela de permissão OAuth 2.0.

Você vai ser redirecionado para uma página com uma mensagem indicando que a autorização foi bem-sucedida.
```
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, o ID do cliente e a chave secreta do cliente para o arquivo googleads.properties ou salve-os em outro lugar para usar se instanciar a biblioteca no ambiente de execução.

A biblioteca pode ser inicializada usando as credenciais do OAuth 2.0 do usuário. Para isso, defina o seguinte em googleads.properties:

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

Como alternativa, use 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_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.

Para Perl, normalmente você implementaria um fluxo de aplicativo da Web em que seu aplicativo lida com 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
loginCustomerId=LOGIN_CUSTOMER_ID

Como alternativa, use 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_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

É comum que um usuário gerencie mais de uma conta do Google Ads, seja por acesso direto às contas 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.