Configuração

A biblioteca de cliente Perl da API Google Ads oferece várias configurações que você pode usar para personalizar o comportamento da biblioteca.

Arquivo de configuração

É possível especificar um arquivo googleads.properties para usar ao instanciar o cliente.

Se você não usar argumentos ao instanciar:

my $api_client = Google::Ads::GoogleAds::Client->new();

A biblioteca procura o arquivo no diretório HOME ou no caminho especificado na variável de ambiente GOOGLE_ADS_CONFIGURATION_FILE_PATH, se ela estiver definida.

Como alternativa, você pode especificar um caminho explicitamente:

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file,
});

Nesse caso, o cliente procura o arquivo nesse caminho.

A maneira mais fácil de gerar esse arquivo é copiar googleads.properties do repositório do GitHub e modificar para incluir seu ID do cliente, chave secreta do cliente e token de atualização.

Configuração dinâmica

É possível configurar dinamicamente ao instanciar a biblioteca ou após a instanciação:

my $api_client = Google::Ads::GoogleAds::Client->new({
  login_customer_id => "INSERT_LOGIN_CUSTOMER_ID_HERE",
});

Também é possível modificar a configuração após a instanciação:

$api_client->set_login_customer_id("INSERT_LOGIN_CUSTOMER_ID_HERE");

Também é possível receber um objeto OAuth2ApplicationsHandler da instância Client e mudar o ID do cliente, a chave secreta do cliente e o token de atualização no tempo de execução:

my $oauth2_applications_handler =
  $api_client->get_oauth2_applications_handler();
$oauth2_applications_handler->set_client_id("INSERT_CLIENT_ID_HERE");
$oauth2_applications_handler->set_client_secret("INSERT_CLIENT_SECRET_HERE");
$oauth2_applications_handler->set_refresh_token("INSERT_REFRESH_TOKEN_HERE");

Variáveis de ambiente de configuração

É possível definir algumas das configurações de variáveis de ambiente ao instanciar clientes. Consulte as variáveis de ambiente padrão.

O módulo Client fornece a função configure_from_environment_variables para carregar valores de variáveis de ambiente.

# Get the Google Ads API Client. By default, any credentials are read from
# ~/googleads.properties, or, if set, from the file specified in the
# GOOGLE_ADS_CONFIGURATION_FILE_PATH environment variable.
my $api_client = Google::Ads::GoogleAds::Client->new();

# Load the configuration from any set environment variables.
$api_client->configure_from_environment_variables();

Campos de configuração

As chaves googleads.properties usam camelCase (como loginCustomerId e linkedCustomerId), enquanto os argumentos do construtor Client->new({...}) e os métodos de manipulador usam snake_case (como login_customer_id e linked_customer_id).

Campos persistidos em OAuth2ApplicationsHandler:

  • client_id (clientId em googleads.properties, GOOGLE_ADS_CLIENT_ID): seu ID do cliente OAuth2.
  • client_secret (clientSecret em googleads.properties, GOOGLE_ADS_CLIENT_SECRET): sua chave secreta do cliente OAuth2.
  • refresh_token (refreshToken em googleads.properties, GOOGLE_ADS_REFRESH_TOKEN): seu token de atualização do OAuth2.
  • additional_scopes (additionalScopes em googleads.properties): outros escopos do OAuth2 a serem solicitados.

Campos persistidos em OAuth2ServiceAccountsHandler:

  • json_key_file_path (jsonKeyFilePath em googleads.properties, GOOGLE_ADS_JSON_KEY_FILE_PATH): o caminho para o arquivo de chave JSON da conta de serviço.
  • impersonated_email (impersonatedEmail em googleads.properties, GOOGLE_ADS_IMPERSONATED_EMAIL): o endereço de e-mail a ser representado ao usar a delegação em todo o domínio do Google Workspace.
  • additional_scopes (additionalScopes em googleads.properties): outros escopos do OAuth2 a serem solicitados.

Campos persistidos em Client:

  • developer_token (developerToken em googleads.properties, GOOGLE_ADS_DEVELOPER_TOKEN): (Desativação em 9 de setembro de 2026) Seu token de desenvolvedor da API Google Ads. Opcional, ignorado pelos servidores de API, seja qual for a versão da biblioteca de cliente, e será rejeitado em uma futura versão principal da API Google Ads.
    • v35.0.0 e versões mais recentes: não é necessário na inicialização do cliente. A validação local do lado do cliente developerToken foi removida no v35.0.0.
    • Versões anteriores a v35.0.0: exigido pela validação de configuração local do lado do cliente se você não fez upgrade para v35.0.0 ou uma versão mais recente.
  • login_customer_id (loginCustomerId em googleads.properties, GOOGLE_ADS_LOGIN_CUSTOMER_ID): o ID da conta de administrador usada para acessar a conta de cliente. Consulte a documentação login-customer-id.
  • linked_customer_id (linkedCustomerId em googleads.properties, GOOGLE_ADS_LINKED_CUSTOMER_ID): o ID de cliente vinculado.
  • service_address (serviceAddress em googleads.properties, GOOGLE_ADS_ENDPOINT): o URL do endereço do serviço da API Google Ads (o padrão é "https://googleads.googleapis.com").
  • user_agent (userAgent em googleads.properties, GOOGLE_ADS_PERL_USER_AGENT): prefixo de cabeçalho user-agent personalizado incluído em solicitações HTTP.
  • proxy (proxy em googleads.properties, GOOGLE_ADS_PERL_PROXY): o URL do servidor proxy usado para conectividade com a Internet.
  • version (Client->new ou set_version): o módulo da versão da API Google Ads a ser usado (o padrão é "V25").
  • die_on_faults (Client->new ou set_die_on_faults): defina como 1 para que os métodos de serviço chamem die() com o payload de resposta bruta em erros de API, em vez de retornar um objeto Google::Ads::GoogleAds::GoogleAdsException (o padrão é 0).
  • http_timeout (Client->new ou set_http_timeout): o tempo limite de HTTP em segundos (o padrão é 3600).
  • http_retry_timing (Client->new ou set_http_retry_timing): intervalos de pausa para novas tentativas em segundos para erros HTTP 503 e 504 temporários (o padrão é "5,10,15").