Конфигурация

Клиентская библиотека PHP для Google Ads API предоставляет несколько настроек, которые можно использовать для изменения ее поведения.

Файл конфигурации

Большинство этих настроек можно сохранить в файлах конфигурации INI и использовать их при создании экземпляров клиентов, например google_ads_php.ini.

В конструкторах учетных данных и клиентов есть методы fromFile для загрузки настроек из таких файлов:

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

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

Если путь к конфигурации не указан в качестве аргумента, методы fromFile загружаются из пути к конфигурации по умолчанию:

1. Значение переменной среды с названием GOOGLE_ADS_CONFIGURATION_FILE_PATH, если оно задано.
2. В противном случае – файл google_ads_php.ini в каталоге HOME.

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

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

Динамическая конфигурация

При создании экземпляров клиентов можно динамически задавать следующие настройки:

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

Переменные среды конфигурации

Некоторые настройки конфигурации можно задать с помощью переменных среды при создании экземпляров клиентов (см. стандартные переменные среды).

В конструкторах учетных данных и клиентов есть методы fromEnvironmentVariables для загрузки настроек из переменных среды.

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

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

Поля конфигурации

Настройки конфигурации поддерживают несколько полей, упорядоченных по категориям:

1. Поля, используемые OAuth2TokenBuilder:
   • Режим приложения:
     • [OAUTH2] clientId – идентификатор клиента OAuth2.
     • [OAUTH2] clientSecret – секретный код клиента OAuth2.
     • [OAUTH2] refreshToken – ваш токен обновления OAuth2.
   • Режим сервисного аккаунта:
     • [OAUTH2] jsonKeyFilePath – путь к ключу JSON.
     • [OAUTH2] scopes – области действия OAuth2 (по умолчанию https://www.googleapis.com/auth/adwords в v32.1.0 и более поздних версиях; требуется в версиях до v32.1.0 или при использовании пользовательских областей действия; не считывается из переменной среды fromEnvironmentVariables()).
     • [OAUTH2] impersonatedEmail – необязательный адрес электронной почты, который можно использовать для делегирования доступа к домену Google Workspace.
   • Режим Application Default Credentials:
     • Если не заданы поля Application mode (Режим приложения) и Service account mode (Режим сервисного аккаунта), OAuth2TokenBuilder автоматически возвращается к учетным данным по умолчанию для приложения (ADC).
2. Поля, используемые GoogleAdsClientBuilder:
   • [GOOGLE_ADS] loginCustomerId – идентификатор авторизованного клиента, который нужно использовать в запросе.
   • [GOOGLE_ADS] linkedCustomerId – идентификатор связанного клиента.
   • [GOOGLE_ADS] endpoint – необязательная альтернативная конечная точка сервера Google Ads API.
   • [LOGGING] logFilePath – путь для вывода журнала.
   • [LOGGING] logLevel – уровень ведения журнала.
   • [CONNECTION] proxy – URL прокси-сервера, используемого для подключения к интернету.
   • [CONNECTION] transport – сетевой транспорт (grpc или rest).
   • [CONNECTION] grpcChannelIsSecure – защищен ли канал gRPC.
   • [CONNECTION] grpcChannelCredential: учетные данные канала gRPC.
   • [CONNECTION] unaryMiddlewares: унарные промежуточные слои.
   • [CONNECTION] streamingMiddlewares – промежуточное ПО для потоковой передачи.
   • [CONNECTION] grpcInterceptors – перехватчики gRPC.

Проверка конфигурации

Настройки конфигурации проверяются при создании экземпляров клиентов, и в случае их недействительности генерируются исключения. Правила проверки:

1. [OAUTH2] Поля не должны быть заданы одновременно для режима приложения и режима сервисного аккаунта.
2. При использовании режима сервисного аккаунта необходимо задать параметр [OAUTH2] jsonKeyFilePath (в версиях до v32.1.0 также необходимо задать параметр [OAUTH2] scopes; в версии v32.1.0 и более поздних для параметра scopes по умолчанию используется значение https://www.googleapis.com/auth/adwords).
3. При использовании режима приложения необходимо задать [OAUTH2] clientId, [OAUTH2] clientSecret и [OAUTH2] refreshToken.
4. Если заданы, [GOOGLE_ADS] loginCustomerId и [GOOGLE_ADS] linkedCustomerId должны быть положительными числами.
5. Если задано, [CONNECTION] proxy должно быть действительным URL (см. фильтр FILTER_VALIDATE_URL).
6. Если задано, [LOGGING] logLevel должно быть допустимым уровнем ведения журнала PSR, указанным заглавными буквами, например INFO.
7. Если задано, то [CONNECTION] transport должно быть равно grpc или rest.
8. Если для параметра [CONNECTION] transport задано значение grpc, среда должна поддерживать транспорт gRPC (см. руководство по транспорту).
9. Если для параметра [CONNECTION] transport не задано значение grpc, то для параметра [CONNECTION] grpcChannelIsSecure должно быть задано значение true (для подключений REST всегда требуется HTTPS).
10. Параметр [CONNECTION] grpcChannelCredential можно задать, только если для параметра [CONNECTION] transport установлено значение grpc.
11. Параметр [CONNECTION] grpcChannelCredential можно задать, только если для параметра [CONNECTION] grpcChannelIsSecure установлено значение true.