Konfiguration

Die Google Ads API PHP-Clientbibliothek bietet mehrere Konfigurationseinstellungen, mit denen Sie das Bibliotheksverhalten anpassen können.

Konfigurationsdatei

Die meisten dieser Konfigurationseinstellungen können Sie in INI-Konfigurationsdateien speichern und beim Instanziieren von Clients verwenden, z. B. google_ads_php.ini.

Sowohl der Anmeldedaten- als auch der Client-Builder bieten fromFile-Methoden zum Laden von Einstellungen aus solchen Dateien:

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

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

Wenn kein Konfigurationspfad als Argument angegeben wird, werden die fromFile-Methoden aus dem Standardkonfigurationspfad geladen:

  1. Der Wert der Umgebungsvariablen mit dem Namen GOOGLE_ADS_CONFIGURATION_FILE_PATH, falls festgelegt.
  2. Andernfalls die Datei google_ads_php.ini in Ihrem Verzeichnis HOME.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

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

Dynamische Konfiguration

Sie können diese Konfigurationseinstellungen dynamisch festlegen, wenn Sie Clients instanziieren:

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

Konfigurationsumgebungsvariablen

Sie können einige der Konfigurationseinstellungen beim Instanziieren von Clients über Umgebungsvariablen festlegen (siehe Standardumgebungsvariablen).

Sowohl die Anmeldedaten- als auch die Client-Builder bieten fromEnvironmentVariables-Methoden zum Laden von Einstellungen aus Umgebungsvariablen.

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

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

Felder für die Konfiguration

Die Konfigurationseinstellungen unterstützen mehrere Felder, die in Kategorien unterteilt sind:

  1. Von OAuth2TokenBuilder verwendete Felder:
    • Anwendungsmodus:
      • [OAUTH2] clientId: Ihre OAuth2-Client-ID.
      • [OAUTH2] clientSecret: Ihr OAuth2-Clientschlüssel.
      • [OAUTH2] refreshToken: Ihr OAuth2-Aktualisierungstoken.
    • Dienstkontomodus:
      • [OAUTH2] jsonKeyFilePath: Der JSON-Schlüsselpfad.
      • [OAUTH2] scopes: Die OAuth2-Bereiche (standardmäßig https://www.googleapis.com/auth/adwords in v32.1.0 und höher; erforderlich in Versionen vor v32.1.0 oder bei Verwendung benutzerdefinierter Bereiche; wird nicht von fromEnvironmentVariables() aus einer Umgebungsvariable gelesen).
      • [OAUTH2] impersonatedEmail: Optionale E-Mail-Adresse, die bei der Verwendung der domainweiten Delegierung von Google Workspace imitiert werden soll.
    • Modus für Standardanmeldedaten für Anwendungen:
      • Wenn weder die Felder für den Anwendungsmodus noch für den Dienstkontomodus festgelegt sind, greift OAuth2TokenBuilder automatisch auf die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) zurück.
  2. Von GoogleAdsClientBuilder verwendete Felder:
    • [GOOGLE_ADS] developerToken: (Wird am 9. September 2026 eingestellt) Ihr Google Ads API-Entwicklertoken. Optional, wird von API-Servern unabhängig von der Clientbibliotheksversion ignoriert und in einer zukünftigen Hauptversion der Google Ads API abgelehnt.
      • v35.0.0 und höher: Nicht bei der Clientinitialisierung erforderlich (GoogleAdsClientBuilder entfernt die lokale clientseitige Validierung des Entwicklertokens).
      • Versionen vor v35.0.0: Erforderlich für die lokale clientseitige Konfigurationsvalidierung.
    • [GOOGLE_ADS] loginCustomerId: Die ID des autorisierten Kunden, die in der Anfrage verwendet werden soll.
    • [GOOGLE_ADS] linkedCustomerId: Die verknüpfte Kunden-ID.
    • [GOOGLE_ADS] endpoint: Optionaler alternativer Google Ads API-Serverendpunkt.
    • [LOGGING] logFilePath: Der Pfad für die Logausgabe.
    • [LOGGING] logLevel: Die Logging-Ebene.
    • [CONNECTION] proxy: Die Proxyserver-URL, die für die Internetverbindung verwendet wird.
    • [CONNECTION] transport: Der Netzwerktransport (grpc oder rest).
    • [CONNECTION] grpcChannelIsSecure: Gibt an, ob der gRPC-Channel sicher ist.
    • [CONNECTION] grpcChannelCredential: Die Anmeldedaten für den gRPC-Channel.
    • [CONNECTION] unaryMiddlewares: Die unären Middlewares.
    • [CONNECTION] streamingMiddlewares: Die Streaming-Middlewares.
    • [CONNECTION] grpcInterceptors: Die gRPC-Interceptors.

Konfigurationsprüfung

Die Konfigurationseinstellungen werden beim Instanziieren von Clients geprüft. Bei ungültigen Einstellungen werden Ausnahmen ausgelöst. Die Validierungsregeln sind:

  1. [OAUTH2]-Felder dürfen nicht gleichzeitig für den Anwendungs- und den Dienstkontomodus festgelegt werden.
  2. [OAUTH2] jsonKeyFilePath muss festgelegt werden, wenn der Dienstkontomodus verwendet wird. In Versionen vor v32.1.0 muss auch [OAUTH2] scopes festgelegt werden. In v32.1.0 und höher wird scopes standardmäßig auf https://www.googleapis.com/auth/adwords gesetzt.
  3. [OAUTH2] clientId, [OAUTH2] clientSecret und [OAUTH2] refreshToken müssen festgelegt werden, wenn der Anwendungsmodus verwendet wird.
  4. In Versionen vor v35.0.0 wird [GOOGLE_ADS] developerToken durch die lokale clientseitige Validierung geprüft. In v35.0.0 und höher ist [GOOGLE_ADS] developerToken nicht erforderlich.
  5. Wenn dieser Wert festgelegt ist, müssen [GOOGLE_ADS] loginCustomerId und [GOOGLE_ADS] linkedCustomerId positive Zahlen sein.
  6. Falls festgelegt, muss [CONNECTION] proxy eine gültige URL sein (siehe FILTER_VALIDATE_URL-Filter).
  7. Falls festgelegt, muss [LOGGING] logLevel ein gültiger PSR-Log-Level in Großbuchstaben sein, z. B. INFO.
  8. Falls festgelegt, muss [CONNECTION] transport entweder grpc oder rest sein.
  9. Wenn [CONNECTION] transport auf grpc gesetzt ist, muss der gRPC-Transport von der Umgebung unterstützt werden (siehe Transportleitfaden).
  10. [CONNECTION] grpcChannelIsSecure muss true sein, wenn [CONNECTION] transport nicht auf grpc festgelegt ist (REST-Verbindungen erfordern immer HTTPS).
  11. [CONNECTION] grpcChannelCredential kann nur festgelegt werden, wenn [CONNECTION] transport auf grpc gesetzt ist.
  12. [CONNECTION] grpcChannelCredential kann nur festgelegt werden, wenn [CONNECTION] grpcChannelIsSecure true ist.