Configurazione

La libreria client PHP dell'API Google Ads fornisce diverse impostazioni di configurazione che puoi utilizzare per personalizzare il comportamento della libreria.

File di configurazione

Puoi archiviare la maggior parte di queste impostazioni di configurazione in file di configurazione INI e utilizzarli quando crei istanze dei client, ad esempio google_ads_php.ini.

I builder di credenziali e client forniscono entrambi metodi fromFile per caricare le impostazioni da questi file:

$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 non viene fornito alcun percorso di configurazione come argomento, i metodi fromFile vengono caricati dal percorso di configurazione predefinito, ovvero:

  1. Il valore della variabile di ambiente denominata GOOGLE_ADS_CONFIGURATION_FILE_PATH, se impostata.
  2. In caso contrario, il file google_ads_php.ini nella directory HOME.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

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

Configurazione dinamica

Puoi impostare queste impostazioni di configurazione in modo dinamico durante l'istanza dei client:

$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();

Variabili di ambiente di configurazione

Puoi impostare alcune impostazioni di configurazione dalle variabili di ambiente durante l'istanza dei client (vedi le variabili di ambiente standard).

I generatori di credenziali e client forniscono entrambi metodi fromEnvironmentVariables per caricare le impostazioni dalle variabili di ambiente.

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

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

Campi di configurazione

Le impostazioni di configurazione supportano diversi campi organizzati in categorie:

  1. Campi utilizzati da OAuth2TokenBuilder:
    • Modalità applicazione:
      • [OAUTH2] clientId: il tuo ID client OAuth2.
      • [OAUTH2] clientSecret: il client secret OAuth2.
      • [OAUTH2] refreshToken: il token di aggiornamento OAuth2.
    • Modalità service account:
      • [OAUTH2] jsonKeyFilePath: il percorso della chiave JSON.
      • [OAUTH2] scopes: gli ambiti OAuth2 (il valore predefinito è https://www.googleapis.com/auth/adwords in v32.1.0 e versioni successive; obbligatori nelle versioni precedenti a v32.1.0 o quando si utilizzano ambiti personalizzati; non letti da una variabile di ambiente da fromEnvironmentVariables()).
      • [OAUTH2] impersonatedEmail: indirizzo email facoltativo da impersonare quando utilizzi la delega a livello di dominio di Google Workspace.
    • Modalità Credenziali predefinite dell'applicazione:
      • Quando non sono impostati i campi Modalità applicazione e Modalità service account, OAuth2TokenBuilder esegue automaticamente il fallback alle credenziali predefinite dell'applicazione (ADC).
  2. Campi utilizzati da GoogleAdsClientBuilder:
    • [GOOGLE_ADS] developerToken: (ritiro il 9 settembre 2026) Il token sviluppatore dell'API Google Ads. Facoltativo, ignorato dai server API indipendentemente dalla versione della libreria client e verrà rifiutato in una futura versione principale dell'API Google Ads.
      • v35.0.0 e versioni successive: non richiesto all'inizializzazione del client (GoogleAdsClientBuilder rimossa la convalida del token sviluppatore lato client locale).
      • Versioni precedenti a v35.0.0: richieste dalla convalida della configurazione lato client locale.
    • [GOOGLE_ADS] loginCustomerId: l'ID del cliente autorizzato da utilizzare nella richiesta.
    • [GOOGLE_ADS] linkedCustomerId: l'ID cliente collegato.
    • [GOOGLE_ADS] endpoint: endpoint del server API Google Ads alternativo facoltativo.
    • [LOGGING] logFilePath: il percorso per l'output di logging.
    • [LOGGING] logLevel: il livello di logging.
    • [CONNECTION] proxy: l'URL del server proxy utilizzato per la connettività a internet.
    • [CONNECTION] transport: il trasporto di rete (grpc o rest).
    • [CONNECTION] grpcChannelIsSecure: Indica se il canale gRPC è sicuro.
    • [CONNECTION] grpcChannelCredential: le credenziali del canale gRPC.
    • [CONNECTION] unaryMiddlewares: I middleware unari.
    • [CONNECTION] streamingMiddlewares: I middleware di streaming.
    • [CONNECTION] grpcInterceptors: gli intercettori gRPC.

Convalida della configurazione

Le impostazioni di configurazione vengono controllate durante l'istanza dei client e vengono generate eccezioni quando non sono valide. Le regole di convalida sono le seguenti:

  1. I campi [OAUTH2] non devono essere impostati contemporaneamente per la modalità Applicazione e la modalità Service account.
  2. [OAUTH2] jsonKeyFilePath deve essere impostato quando si utilizza la modalità Service account (nelle versioni precedenti a v32.1.0, deve essere impostato anche [OAUTH2] scopes; in v32.1.0 e versioni successive, scopes è impostato per impostazione predefinita su https://www.googleapis.com/auth/adwords).
  3. [OAUTH2] clientId, [OAUTH2] clientSecret e [OAUTH2] refreshToken devono essere impostati quando si utilizza la modalità Applicazione.
  4. Nelle versioni precedenti a v35.0.0, [GOOGLE_ADS] developerToken viene controllato dalla convalida lato client locale (in v35.0.0 e versioni successive, [GOOGLE_ADS] developerToken non è obbligatorio).
  5. Se impostati, [GOOGLE_ADS] loginCustomerId e [GOOGLE_ADS] linkedCustomerId devono essere numeri positivi.
  6. Se impostato, [CONNECTION] proxy deve essere un URL valido (vedi il filtro FILTER_VALIDATE_URL).
  7. Se impostato, [LOGGING] logLevel deve essere un livello di log PSR valido in lettere maiuscole, ad esempio INFO.
  8. Se impostato, [CONNECTION] transport deve essere grpc o rest.
  9. Se [CONNECTION] transport è impostato su grpc, il trasporto gRPC deve essere supportato dall'ambiente (vedi la guida al trasporto).
  10. [CONNECTION] grpcChannelIsSecure deve essere true quando [CONNECTION] transport non è impostato su grpc (le connessioni REST richiedono sempre HTTPS).
  11. [CONNECTION] grpcChannelCredential può essere impostato solo quando [CONNECTION] transport è impostato su grpc.
  12. [CONNECTION] grpcChannelCredential può essere impostato solo quando [CONNECTION] grpcChannelIsSecure è true.