O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configuração

A biblioteca de cliente PHP 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 armazenar a maioria dessas configurações em arquivos de configuração INI e usá-los ao instanciar clientes, por exemplo, google_ads_php.ini.

Os criadores de credenciais e clientes fornecem métodos fromFile para carregar configurações desses arquivos:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Se nenhum caminho de configuração for fornecido como argumento, os métodos fromFile serão carregados do caminho de configuração padrão, que é:

O valor da variável de ambiente chamada GOOGLE_ADS_CONFIGURATION_FILE_PATH, se definida.
Caso contrário, o arquivo google_ads_php.ini no diretório HOME.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Configuração dinâmica

É possível definir essas configurações de forma dinâmica ao instanciar clientes:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

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.

Os criadores de credenciais e clientes fornecem métodos fromEnvironmentVariables para carregar configurações de variáveis de ambiente.

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // ...
    ->fromEnvironmentVariables()
    ->build();

Campos de configuração

As configurações de configuração oferecem suporte a vários campos organizados em categorias:

Campos usados por OAuth2TokenBuilder:
- Modo de aplicativo:
  - [OAUTH2] clientId: seu ID do cliente OAuth2.
  - [OAUTH2] clientSecret: sua chave secreta do cliente OAuth2.
  - [OAUTH2] refreshToken: seu token de atualização do OAuth2.
- Modo da conta de serviço:
  - [OAUTH2] jsonKeyFilePath: o caminho da chave JSON.
  - [OAUTH2] scopes: os escopos do OAuth2 (o padrão é https://www.googleapis.com/auth/adwords no v32.1.0 e versões mais recentes; obrigatório em versões anteriores ao v32.1.0 ou ao usar escopos personalizados; não é lido de uma variável de ambiente pelo fromEnvironmentVariables()).
  - [OAUTH2] impersonatedEmail: endereço de e-mail opcional para representar ao usar a delegação em todo o domínio do Google Workspace.
- Modo Application Default Credentials:
  - Quando nenhum dos campos "Modo de aplicativo" ou "Modo de conta de serviço" está definido, o OAuth2TokenBuilder volta automaticamente para as credenciais padrão do aplicativo (ADC, na sigla em inglês).
Campos usados por GoogleAdsClientBuilder:
- [GOOGLE_ADS] developerToken: (desativação em 9 de setembro de 2026) seu token de desenvolvedor da API Google Ads. Opcional, ignorado pelos servidores de API, independente da versão da biblioteca de cliente, e será rejeitado em uma versão principal futura da API Google Ads.
  - v35.0.0 e versões mais recentes: não é necessário na inicialização do cliente. (GoogleAdsClientBuilder removeu a validação do token de desenvolvedor local do lado do cliente).
  - Versões anteriores a v35.0.0: exigidas pela validação local da configuração do lado do cliente.
- [GOOGLE_ADS] loginCustomerId: o ID do cliente autorizado a ser usado na solicitação.
- [GOOGLE_ADS] linkedCustomerId: o ID do cliente vinculado.
- [GOOGLE_ADS] endpoint: endpoint alternativo opcional do servidor da API Google Ads.
- [LOGGING] logFilePath: o caminho para a saída de geração de registros.
- [LOGGING] logLevel: o nível de registro.
- [CONNECTION] proxy: o URL do servidor proxy usado para conectividade com a Internet.
- [CONNECTION] transport: o transporte de rede (grpc ou rest).
- [CONNECTION] grpcChannelIsSecure: indica se o canal gRPC é seguro.
- [CONNECTION] grpcChannelCredential: as credenciais do canal gRPC.
- [CONNECTION] unaryMiddlewares: os middlewares unários.
- [CONNECTION] streamingMiddlewares: os middlewares de streaming.
- [CONNECTION] grpcInterceptors: os interceptores do gRPC.

Validação de configuração

As configurações de configuração são verificadas ao instanciar clientes, e exceções são geradas quando inválidas. As regras de validação são as seguintes:

Os campos [OAUTH2] não podem ser definidos para o modo de aplicativo e o modo de conta de serviço ao mesmo tempo.
[OAUTH2] jsonKeyFilePath precisa ser definido ao usar o modo de conta de serviço. Em versões anteriores a v32.1.0, [OAUTH2] scopes também precisa ser definido. Em v32.1.0 e versões mais recentes, scopes usa https://www.googleapis.com/auth/adwords por padrão.
[OAUTH2] clientId, [OAUTH2] clientSecret e [OAUTH2] refreshToken precisam ser definidos ao usar o modo de aplicativo.
Em versões anteriores a v35.0.0, [GOOGLE_ADS] developerToken é verificado pela validação local do lado do cliente. Em v35.0.0 e versões mais recentes, [GOOGLE_ADS] developerToken não é obrigatório.
Se definidos, [GOOGLE_ADS] loginCustomerId e [GOOGLE_ADS] linkedCustomerId precisam ser números positivos.
Se definido, [CONNECTION] proxy precisa ser um URL válido (consulte o filtro FILTER_VALIDATE_URL).
Se definido, [LOGGING] logLevel precisa ser um nível de registro PSR válido em letras maiúsculas, como INFO.
Se definido, [CONNECTION] transport precisa ser grpc ou rest.
Se [CONNECTION] transport estiver definido como grpc, o transporte gRPC precisará ser compatível com o ambiente. Consulte o guia de transporte.
[CONNECTION] grpcChannelIsSecure precisa ser true quando [CONNECTION] transport não está definido como grpc (as conexões REST sempre exigem HTTPS).
[CONNECTION] grpcChannelCredential só pode ser definido quando [CONNECTION] transport está definido como grpc.
[CONNECTION] grpcChannelCredential só pode ser definido quando [CONNECTION] grpcChannelIsSecure é true.