Configuração

É possível configurar a biblioteca de cliente do 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 que você usa. Para mais informações, consulte o guia de autenticação.

Configuração usando o arquivo YAML

É possível especificar um arquivo YAML para usar 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 exemplo google-ads.yaml 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 onde 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 ambos os valores forem fornecidos (um caminho é transmitido para o método e a variável de ambiente está presente), a biblioteca prioriza 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 daquelas 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 geralmente 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.

Veja 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"]

Veja 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 amostra google-ads.yaml.

Veja 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"
    }
  }
}'

Importante: 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ê leu um arquivo YAML na memória, pode 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. 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 é compatível com os campos a seguir.

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 (documentação)
    • use_application_default_credentials: se a biblioteca deve 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: o 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 que será representada ao usar a delegação em todo o domínio do Google Workspace.

Comportamento da biblioteca

Esses campos determinam o comportamento da biblioteca:

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

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 (compatível com o v28.3.0 e versões mais recentes)

Configuração de registros

Os campos de registro, que estão 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 método logging.config.dictConfig. Consulte o guia de geração de registros para ver todos os detalhes.

  • version: um valor inteiro que representa uma versão do esquema.
  • disable_existing_loggers: se os loggers 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 devem ser usados.
  • loggers: dicionários que definem diferentes tipos de loggers, que incluem um gerenciador e um nível de registro.