設定

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：用於網際網路連線的 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 (REST 連線一律需要 HTTPS)，則 [CONNECTION] grpcChannelIsSecure 必須為 true。
  11. 只有在 [CONNECTION] transport 設為 grpc 時，才能設定 [CONNECTION] grpcChannelCredential。
  12. 只有在 [CONNECTION] grpcChannelIsSecure 為 true 時，才能設定 [CONNECTION] grpcChannelCredential。