Konfiguracja

Biblioteka klienta interfejsu Google Ads API dla języka PHP udostępnia kilka ustawień konfiguracyjnych, których możesz użyć do dostosowania działania biblioteki.

Plik konfiguracji

Większość tych ustawień konfiguracji możesz przechowywać w plikach konfiguracyjnych INI i używać ich podczas tworzenia instancji klientów, np. google_ads_php.ini.

Zarówno narzędzie do tworzenia uwierzytelniania, jak i klienta udostępniają metody fromFile do wczytywania ustawień z takich plików:

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

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

Jeśli ścieżka konfiguracji nie zostanie podana jako argument, metody fromFile wczytują się z domyślnej ścieżki konfiguracji, czyli:

  1. Wartość zmiennej środowiskowej o nazwie GOOGLE_ADS_CONFIGURATION_FILE_PATH, jeśli jest ustawiona.
  2. W przeciwnym razie plik google_ads_php.ini w katalogu HOME.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

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

Konfiguracja dynamiczna

Te ustawienia konfiguracji możesz ustawiać dynamicznie podczas tworzenia instancji klientów:

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

Zmienne środowiskowe konfiguracji

Niektóre ustawienia konfiguracji możesz określić za pomocą zmiennych środowiskowych podczas tworzenia instancji klientów (patrz standardowe zmienne środowiskowe).

Konstruktory danych logowania i klienta udostępniają metody fromEnvironmentVariables do wczytywania ustawień ze zmiennych środowiskowych.

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

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

Pola konfiguracji

Ustawienia konfiguracji obsługują kilka pól podzielonych na kategorie:

  1. Pola używane przez OAuth2TokenBuilder:
    • Tryb aplikacji:
      • [OAUTH2] clientId: identyfikator klienta OAuth2.
      • [OAUTH2] clientSecret: tajny klucz klienta OAuth2.
      • [OAUTH2] refreshToken: token odświeżania OAuth2.
    • Tryb konta usługi:
      • [OAUTH2] jsonKeyFilePath: ścieżka klucza JSON.
      • [OAUTH2] scopes: zakresy OAuth2 (domyślnie https://www.googleapis.com/auth/adwords w wersji v32.1.0 i nowszych; wymagane w wersjach starszych niż v32.1.0 lub w przypadku używania zakresów niestandardowych; nie są odczytywane ze zmiennej środowiskowej przez fromEnvironmentVariables()).
      • [OAUTH2] impersonatedEmail: opcjonalny adres e-mail, który ma być używany podczas przekazywania dostępu w całej domenie Google Workspace.
    • Tryb domyślnego uwierzytelniania aplikacji:
      • Jeśli nie ustawiono pól Tryb aplikacji ani Tryb konta usługi, OAuth2TokenBuilder automatycznie przełącza się na domyślne dane logowania aplikacji (ADC).
  2. Pola używane przez GoogleAdsClientBuilder:
    • [GOOGLE_ADS] developerToken: (Wycofanie 9 września 2026 r.) Twój token deweloperski interfejsu Google Ads API. Opcjonalne, ignorowane przez serwery interfejsu API niezależnie od wersji biblioteki klienta. W przyszłej głównej wersji interfejsu Google Ads API będą odrzucane.
      • v35.0.0 i nowsze: nie jest wymagany podczas inicjowania klienta (GoogleAdsClientBuilder usunięto lokalną weryfikację tokena programisty po stronie klienta).
      • Wersje starsze niż v35.0.0: wymagane przez lokalną weryfikację konfiguracji po stronie klienta.
    • [GOOGLE_ADS] loginCustomerId: identyfikator autoryzowanego klienta, który ma być użyty w żądaniu.
    • [GOOGLE_ADS] linkedCustomerId: połączony identyfikator klienta.
    • [GOOGLE_ADS] endpoint: opcjonalny alternatywny punkt końcowy serwera interfejsu Google Ads API.
    • [LOGGING] logFilePath: ścieżka do danych wyjściowych logowania.
    • [LOGGING] logLevel: poziom rejestrowania.
    • [CONNECTION] proxy: adres URL serwera proxy używany do połączenia z internetem.
    • [CONNECTION] transport: transport sieciowy (grpc lub rest).
    • [CONNECTION] grpcChannelIsSecure: czy kanał gRPC jest bezpieczny.
    • [CONNECTION] grpcChannelCredential: dane logowania kanału gRPC.
    • [CONNECTION] unaryMiddlewares: pośredniki unarne.
    • [CONNECTION] streamingMiddlewares: oprogramowanie pośredniczące do streamingu.
    • [CONNECTION] grpcInterceptors: przechwytujące gRPC.

Sprawdzanie poprawności konfiguracji

Ustawienia konfiguracji są sprawdzane podczas tworzenia instancji klientów, a w przypadku nieprawidłowych ustawień zgłaszane są wyjątki. Obowiązują te reguły weryfikacji:

  1. Pola [OAUTH2] nie mogą być ustawione jednocześnie w trybie aplikacji i w trybie konta usługi.
  2. [OAUTH2] jsonKeyFilePath musi być ustawiona podczas korzystania z trybu konta usługi (w wersjach wcześniejszych niż v32.1.0 musi być też ustawiona wartość [OAUTH2] scopes; w wersji v32.1.0 i nowszych wartość scopes jest domyślnie ustawiona na https://www.googleapis.com/auth/adwords).
  3. W trybie aplikacji należy ustawić wartości [OAUTH2] clientId, [OAUTH2] clientSecret i [OAUTH2] refreshToken.
  4. W wersjach starszych niż v35.0.0 wartość [GOOGLE_ADS] developerToken jest sprawdzana przez lokalną weryfikację po stronie klienta (w wersji v35.0.0 i nowszych wartość [GOOGLE_ADS] developerToken nie jest wymagana).
  5. Jeśli te parametry są ustawione, [GOOGLE_ADS] loginCustomerId i [GOOGLE_ADS] linkedCustomerId muszą być liczbami dodatnimi.
  6. Jeśli jest ustawiony, parametr [CONNECTION] proxy musi być prawidłowym adresem URL (patrz FILTER_VALIDATE_URL filtr).
  7. Jeśli to pole jest ustawione, [LOGGING] logLevel musi być prawidłowym poziomem logowania PSR zapisanym wielkimi literami, np. INFO.
  8. Jeśli ta wartość jest ustawiona, [CONNECTION] transport musi mieć wartość grpc lub rest.
  9. Jeśli wartość [CONNECTION] transport to grpc, środowisko musi obsługiwać transport gRPC (patrz przewodnik po transporcie).
  10. Wartość parametru [CONNECTION] grpcChannelIsSecure musi być równa true, jeśli parametr [CONNECTION] transport nie ma wartości grpc (połączenia REST zawsze wymagają protokołu HTTPS).
  11. Parametr [CONNECTION] grpcChannelCredential można ustawić tylko wtedy, gdy parametr [CONNECTION] transport ma wartość grpc.
  12. Ustawienie [CONNECTION] grpcChannelCredential można skonfigurować tylko wtedy, gdy ustawienie [CONNECTION] grpcChannelIsSecure ma wartość true.