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 aplicativo 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 maneira eficaz com a API Google Ads, entenda como o modelo de acesso do Google Ads funciona. 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 ele 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. A biblioteca Python é configurada da seguinte maneira:

• Se você estiver usando um arquivo google-ads.yaml ou uma string YAML, adicione o seguinte à configuração para definir o caminho para o arquivo JSON de chave privada no ambiente local (junto com impersonated_email opcional, se estiver usando a delegação em todo o domínio):

  json_key_file_path: JSON_KEY_FILE_PATH
  # Optional: only set if using Google Workspace domain-wide delegation:
  # impersonated_email: IMPERSONATED_EMAIL
  

  Em seguida, chame os métodos load_from_storage ou load_from_string:

  from google.ads.googleads.client import GoogleAdsClient
  
  client = GoogleAdsClient.load_from_storage()
  

• Se você estiver usando um dict para configurar a biblioteca, inclua o seguinte par de chave-valor e chame o método load_from_dict, transmitindo a configuração dict:

  from google.ads.googleads.client import GoogleAdsClient
  
  configuration = {
      # ...
      "json_key_file_path": JSON_KEY_FILE_PATH,
      # ...
  }
  
  client = GoogleAdsClient.load_from_dict(configuration)
  

• Se você estiver usando variáveis de ambiente, adicione o seguinte à configuração ou ambiente bash:

  export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
  

  Em seguida, chame o método load_from_env:

  from google.ads.googleads.client import GoogleAdsClient
  
  client = GoogleAdsClient.load_from_env()
  

Se a opção de configuração json_key_file_path estiver presente em qualquer um desses métodos de configuração, a opção use_application_default_credentials será False ou não definida, e as chaves de credenciais do usuário OAuth (client_id, client_secret e refresh_token) serão não definidas ou comentadas. A biblioteca autoriza automaticamente o uso do fluxo da conta de serviço.

Consulte o guia do 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 a serem gerenciadas usando a API Google Ads. Uma abordagem comum é conceder 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.

2. O usuário executa uma ferramenta, como a CLI gcloud ou o generate_user_credentials exemplo de código para autorizar seu app a gerenciar todas as contas do Google Ads em nome dele.

A biblioteca pode ser inicializada usando as credenciais OAuth 2.0 do usuário da seguinte maneira:

Se você estiver usando a ferramenta da CLI gcloud (recomendado)

1. Siga a documentação Gerar credenciais para configurar o Application Default Credentials (ADC) no ambiente local.

2. Adicione a seguinte configuração à string google-ads.yaml ou YAML:

   use_application_default_credentials: true
   

   Em seguida, chame o método load_from_storage ou load_from_string:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_storage()
   

   Se você usar um dict para configurar a biblioteca, inclua o seguinte par de chave-valor e chame o load_from_dict método:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
       # ...
       "use_application_default_credentials": True,
       # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

   Se você estiver usando variáveis de ambiente, adicione o seguinte à configuração ou ambiente bash:

   export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS=true
   

   Em seguida, chame o método load_from_env:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_env()
   

Se você estiver processando tokens OAuth diretamente

1. Siga as etapas para configurar um projeto do console e fazer o download do arquivo JSON que inclui o ID do cliente e a chave secreta do cliente do projeto.

2. Clone a biblioteca de cliente Python para sua máquina e mude para o diretório dela:

   git clone https://github.com/googleads/google-ads-python.git
   cd google-ads-python
   

3. Execute o exemplo, fornecendo um caminho absoluto para o arquivo JSON transferido por download na etapa 1:

   python examples/authentication/generate_user_credentials.py \
       -c PATH_TO_CREDENTIALS_JSON
   

   Quando concluído, um token de atualização é impresso no console. Copie e salve para a próxima etapa.

4. Configure a biblioteca adicionando as seguintes configurações à configuração de sua escolha:

   Adicione a seguinte configuração à string google-ads.yaml ou YAML:

   client_id: INSERT_OAUTH2_CLIENT_ID_HERE
   client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
   refresh_token: INSERT_REFRESH_TOKEN_HERE
   

   Em seguida, chame o método load_from_storage ou load_from_string:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_storage()
   

   Se você estiver usando um dict para configurar a biblioteca, inclua os seguintes pares de chave-valor e chame o load_from_dict método:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
       # ...
       "client_id": INSERT_OAUTH2_CLIENT_ID_HERE,
       "client_secret": (
           INSERT_OAUTH2_CLIENT_SECRET_HERE
       ),
       "refresh_token": INSERT_REFRESH_TOKEN_HERE,
       # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

   Se você estiver usando variáveis de ambiente, adicione o seguinte à configuração ou ambiente bash:

   export GOOGLE_ADS_CLIENT_ID=\
   INSERT_OAUTH2_CLIENT_ID_HERE
   export GOOGLE_ADS_CLIENT_SECRET=\
   INSERT_OAUTH2_CLIENT_SECRET_HERE
   export GOOGLE_ADS_REFRESH_TOKEN=\
   INSERT_REFRESH_TOKEN_HERE
   

   Em seguida, chame o método load_from_env:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_env()
   

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 app cria e gerencia as credenciais de usuário do OAuth 2.0. A biblioteca pode ser inicializada usando as credenciais do usuário da seguinte maneira, que pressupõe que o aplicativo receba credenciais no momento da execução, executando um fluxo de autorização ou carregando-as de um armazenamento de dados:

Um dict é o mecanismo de configuração mais simples a ser usado ao receber credenciais no momento da execução:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": client_id,
    "client_secret": client_secret,
    "refresh_token": refresh_token,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

Autenticação manual

Você pode gerar credenciais de autenticação com qualquer abordagem e fornecê-las ao GoogleAdsClient manualmente, instanciando a classe do cliente diretamente. Supondo que o objeto de credenciais criado seja uma instância de google.auth.credentials.Credentials, você pode transmiti-lo da seguinte maneira:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`.
credentials, _ = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
    credentials=credentials,
    use_proto_plus=True,
)

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 Python fornece os seguintes exemplos de código que ilustram como lidar com esses casos:

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