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 do 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 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 modificar para incluir suas credenciais, incluindo token de atualização, ID do cliente e 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

Você pode 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 maiúsculas e ter o prefixo do namespace GOOGLE_ADS_. Por exemplo, client_id deve 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 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"
    }
  }
}'

Importante: se a variável de ambiente GOOGLE_ADS_CONFIGURATION_FILE_PATH for 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, 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. 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 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 credenciais padrão do aplicativo (documentação)
    • use_application_default_credentials: indica se a biblioteca deve usar credenciais padrão do aplicativo (ADC) para autenticação (compatível com 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. Usado para autenticar com 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 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 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 método logging.config.dictConfig. Consulte o guia de geração de registros para mais detalhes.

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