Configuração

É possível configurar a biblioteca de cliente Python usando um arquivo YAML, variáveis de ambiente, uma string YAML ou um dict.

Configuração da autenticação

Há várias maneiras de gerenciar as credenciais OAuth necessárias para acessar a API Google Ads. A abordagem escolhida afeta os campos de configuração usados. Para mais informações, consulte o guia de autenticação.

Configuração usando um arquivo YAML

É possível especificar um arquivo YAML a ser usado ao inicializar o cliente que contém as informações necessárias para fazer solicitações à API Google Ads. Esse arquivo é acessado quando um cliente é inicializado usando o método load_from_storage. A maneira mais fácil de gerar esse arquivo é copiar o google-ads.yaml exemplo do repositório do GitHub e modificá-lo para incluir suas credenciais, incluindo o token de atualização, o ID do cliente e a chave secreta do cliente.

Se você não fornecer um caminho, a biblioteca vai procurar o arquivo no diretório $HOME:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Para especificar um local em que o arquivo google-ads.yaml está localizado, transmita o caminho como uma string para o método ao chamá-lo:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Também é possível especificar o caminho definindo uma variável de ambiente específica:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

Se os dois valores forem fornecidos (um caminho é transmitido para o método e a variável de ambiente está presente), a biblioteca vai priorizar o caminho transmitido para o método.

Configuração usando variáveis de ambiente

É possível armazenar toda a configuração do cliente como variáveis de ambiente, que são lidas ao usar o método load_from_env do cliente. As variáveis de ambiente precisam ter o mesmo nome das definidas no arquivo google-ads.yaml, mas precisam estar em letras maiúsculas e ter o prefixo do namespace GOOGLE_ADS_. Por exemplo, client_id precisa ser armazenado como GOOGLE_ADS_CLIENT_ID.

As variáveis de ambiente são definidas em um arquivo de configuração do Bash, como um arquivo .bashrc ou .bash_profile localizado no diretório $HOME. Elas também podem ser definidas usando a linha de comando.

Confira algumas etapas básicas para definir uma variável de ambiente usando um arquivo .bashrc em um terminal:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

As variáveis de ambiente também podem ser definidas na instância do terminal diretamente na linha de comando:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

O método load_from_env carrega dados de configuração do atributo environ no módulo os integrado do Python. Por exemplo: os.environ["GOOGLE_ADS_CLIENT_ID"]

Confira um exemplo de como inicializar uma instância de cliente com a configuração de variáveis de ambiente:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Para configurar logging usando variáveis de ambiente, o valor de configuração precisa ser um objeto JSON que corresponda à estrutura das chaves YAML no arquivo de configuração de exemplo google-ads.yaml.

Confira um exemplo de como isso pode ser definido usando um arquivo .bashrc:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Ponto principal: se a variável de ambiente GOOGLE_ADS_CONFIGURATION_FILE_PATH estiver definida quando o método load_from_env for chamado, os valores de configuração serão recuperados do arquivo google-ads.yaml localizado no caminho especificado, e não das variáveis de ambiente descritas anteriormente.

Configuração usando uma string YAML

Se você tiver lido um arquivo YAML na memória, poderá fornecê-lo diretamente ao cliente na inicialização. Para fazer isso, use o método load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Configuração usando um dict

É possível transmitir um dict diretamente para o método load_from_dict. Por exemplo:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Campos de configuração

A configuração da biblioteca de cliente oferece suporte aos seguintes campos.

Autenticação

Use apenas um desses grupos de campos, dependendo da abordagem de autenticação que você está usando:

  • Usuário único com Application Default Credentials (ADC) (documentação)
    • use_application_default_credentials: indica se a biblioteca precisa usar o Application Default Credentials (ADC) para autenticação (com suporte no google-ads v28.3.0 e versões mais recentes).
  • Usuário único com tokens OAuth (documentação)
    • client_id: seu ID do cliente OAuth.
    • client_secret: sua chave secreta do cliente OAuth.
    • refresh_token: seu token de atualização do OAuth.
  • Conta de serviço (documentação)
    • json_key_file_path: um caminho para um arquivo de chave privada local. Isso é usado para autenticação usando uma conta de serviço.
    • impersonated_email: endereço de e-mail opcional da conta a ser representada ao usar a delegação em todo o domínio do Google Workspace.

Comportamento da biblioteca

Esses campos ditam o comportamento da biblioteca:

Configuração no nível da solicitação

  • linked_customer_id: consulte a documentação do ID do cliente vinculado.
  • login_customer_id: consulte a documentação do ID do cliente de login.
  • endpoint: endereço de endpoint de API Google Ads alternativo opcional.
  • ads_assistant: identificador opcional para o cabeçalho do Assistente da API Google Ads.

Variáveis de ambiente

Para configurar a biblioteca usando variáveis de ambiente, use o seguinte:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (com suporte na v28.3.0 e versões mais recentes)

Configuração de registros

Os campos de registro, que são campos abaixo do campo de configuração logging, são derivados diretamente do módulo integrado logging.config, porque a biblioteca transmite todos os campos no namespace logging diretamente para o logging.config.dictConfig método. Consulte o guia de registro para mais detalhes.

  • version: um valor inteiro que representa uma versão do esquema.
  • disable_existing_loggers: indica se os registradores configurados em outro lugar do aplicativo precisam ser desativados.
  • formatters: dicionários que definem diferentes tipos de formatadores.
  • handlers: dicionários que definem diferentes gerenciadores, que controlam onde os registros são gravados e quais formatadores precisam ser usados.
  • loggers: dicionários que definem diferentes tipos de registradores, que incluem um gerenciador e um nível de registro.