配置

Google Ads API PHP 客户端库提供了多种配置设置，您可以使用这些设置来自定义库行为。

配置文件

您可以将大多数此类配置设置存储在 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. 否则，请检查 HOME 目录中的 google_ads_php.ini 文件。
$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 客户端 ID。
      • [OAUTH2] clientSecret：您的 OAuth2 客户端密钥。
      • [OAUTH2] refreshToken：您的 OAuth2 刷新令牌。
    • 服务账号模式：
      • [OAUTH2] jsonKeyFilePath：JSON 密钥路径。
      • [OAUTH2] scopes：OAuth2 范围（在 v32.1.0 及更高版本中默认为 https://www.googleapis.com/auth/adwords；在 v32.1.0 之前的版本中或使用自定义范围时为必需；不会被 fromEnvironmentVariables() 从环境变量中读取）。
      • [OAUTH2] impersonatedEmail：使用 Google Workspace 网域范围的委托时要模拟的可选电子邮件地址。
    • 应用默认凭证模式：
      • 如果未设置“应用模式”字段和“服务账号模式”字段，OAuth2TokenBuilder 会自动回退到应用默认凭据 (ADC)。
  2. GoogleAdsClientBuilder 使用的字段：
    • [GOOGLE_ADS] developerToken：（将于 2026 年 9 月 9 日停用）您的 Google Ads API 开发者令牌。可选，无论客户端库版本如何，API 服务器都会忽略此字段，并且在 Google Ads API 的未来主要版本中，此字段将被拒绝。
      • v35.0.0 及更高版本：在客户端初始化时不需要（移除了 GoogleAdsClientBuilder 本地客户端开发者令牌验证）。
      • v35.0.0 之前的版本：本地客户端配置验证需要此版本。
    • [GOOGLE_ADS] loginCustomerId：要在请求中使用的已获授权的客户的 ID。
    • [GOOGLE_ADS] linkedCustomerId：关联的客户 ID。
    • [GOOGLE_ADS] endpoint：可选的备用 Google Ads API 服务器端点。
    • [LOGGING] logFilePath：日志输出的路径。
    • [LOGGING] logLevel：日志记录级别。
    • [CONNECTION] proxy：用于互联网连接的代理服务器网址。
    • [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. 在 v35.0.0 之前的版本中，[GOOGLE_ADS] developerToken 通过本地客户端验证进行检查（在 v35.0.0 及更高版本中，[GOOGLE_ADS] developerToken 不是必需的）。
  5. 如果设置，[GOOGLE_ADS] loginCustomerId 和 [GOOGLE_ADS] linkedCustomerId 必须为正数。
  6. 如果设置了该值，[CONNECTION] proxy必须是有效的网址（请参阅 FILTER_VALIDATE_URL 过滤条件）。
  7. 如果设置，[LOGGING] logLevel 必须是有效的 PSR 日志级别（大写字母），例如 INFO。
  8. 如果设置了此字段，[CONNECTION] transport 必须为 grpc 或 rest。
  9. 如果 [CONNECTION] transport 设置为 grpc，则环境必须支持 gRPC 传输（请参阅传输指南）。
  10. 当 [CONNECTION] transport 未设置为 grpc 时，[CONNECTION] grpcChannelIsSecure 必须为 true（REST 连接始终需要 HTTPS）。
  11. 只有当 [CONNECTION] transport 设置为 grpc 时，才能设置 [CONNECTION] grpcChannelCredential。
  12. 只有当 [CONNECTION] grpcChannelIsSecure 为 true 时才能设置 [CONNECTION] grpcChannelCredential。