設定

Google Ads API Perl 用戶端程式庫提供多項設定，可供您自訂程式庫行為。

設定檔

您可以在例項化用戶端時，指定要使用的 googleads.properties 檔案。

如果您在例項化時未使用任何引數：

my $api_client = Google::Ads::GoogleAds::Client->new();

然後程式庫會在 HOME 目錄中尋找檔案，或在 GOOGLE_ADS_CONFIGURATION_FILE_PATH 環境變數中指定的路徑 (如有設定) 尋找檔案。

或者，您也可以明確指定路徑：

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file,
});

在這種情況下，用戶端會尋找該路徑的檔案。

如要產生這個檔案，最簡單的方法是從 GitHub 存放區複製 googleads.properties，然後修改檔案，加入用戶端 ID、用戶端密鑰和更新權杖。

動態設定

您可以在例項化程式庫時動態設定設定，也可以在例項化後設定：

my $api_client = Google::Ads::GoogleAds::Client->new({
  login_customer_id => "INSERT_LOGIN_CUSTOMER_ID_HERE",
});

您也可以在例項化後修改設定：

$api_client->set_login_customer_id("INSERT_LOGIN_CUSTOMER_ID_HERE");

您也可以從 Client 執行個體取得 OAuth2ApplicationsHandler 物件，並在執行階段變更用戶端 ID、用戶端密鑰和更新權杖：

my $oauth2_applications_handler =
  $api_client->get_oauth2_applications_handler();
$oauth2_applications_handler->set_client_id("INSERT_CLIENT_ID_HERE");
$oauth2_applications_handler->set_client_secret("INSERT_CLIENT_SECRET_HERE");
$oauth2_applications_handler->set_refresh_token("INSERT_REFRESH_TOKEN_HERE");

注意： 不建議在原始碼中儲存硬式編碼的密鑰。在正式環境中，請使用環境變數或安全屬性檔案。

設定環境變數

您可以在例項化用戶端時，透過環境變數設定部分設定 (請參閱標準環境變數)。

Client 模組提供 configure_from_environment_variables 函式，可從環境變數載入值。

注意： 系統不會將未設定的環境變數納入考量。

# Get the Google Ads API Client. By default, any credentials are read from
# ~/googleads.properties, or, if set, from the file specified in the
# GOOGLE_ADS_CONFIGURATION_FILE_PATH environment variable.
my $api_client = Google::Ads::GoogleAds::Client->new();

# Load the configuration from any set environment variables.
$api_client->configure_from_environment_variables();

設定欄位

請注意，googleads.properties 鍵會使用 camelCase (例如 loginCustomerId 和 linkedCustomerId)，而 Client->new({...}) 建構函式引數和處理常式方法則會使用 snake_case (例如 login_customer_id 和 linked_customer_id)。

OAuth2ApplicationsHandler 中保留的欄位：

• client_id (googleads.properties 中的 clientId，GOOGLE_ADS_CLIENT_ID)： 您的 OAuth2 用戶端 ID。
• client_secret (clientSecret in googleads.properties, GOOGLE_ADS_CLIENT_SECRET)：您的 OAuth2 用戶端密鑰。
• refresh_token (refreshToken in googleads.properties, GOOGLE_ADS_REFRESH_TOKEN)：您的 OAuth2 更新權杖。
• additional_scopes (additionalScopes in googleads.properties)： 要要求的其他 OAuth2 範圍。

OAuth2ServiceAccountsHandler 中保留的欄位：

• json_key_file_path (googleads.properties 中的 GOOGLE_ADS_JSON_KEY_FILE_PATH jsonKeyFilePath)：服務帳戶 JSON 金鑰檔案的路徑。
• impersonated_email (impersonatedEmail in googleads.properties, GOOGLE_ADS_IMPERSONATED_EMAIL)：使用 Google Workspace 網域範圍授權時要模擬的電子郵件地址。
• additional_scopes (additionalScopes in googleads.properties)： 要要求的其他 OAuth2 範圍。

Client 中保留的欄位：

• developer_token (developerToken in googleads.properties, GOOGLE_ADS_DEVELOPER_TOKEN)：(2026 年 9 月 9 日終止服務) 您的 Google Ads API 開發人員權杖。 選用，無論用戶端程式庫版本為何，API 伺服器都會忽略此欄位，且 Google Ads API 未來的主要版本會拒絕此欄位。
  • v35.0.0 以上版本：不需要在用戶端初始化時提供 (v35.0.0 已移除本機用戶端 developerToken 驗證)。
  • v35.0.0之前的版本：如果您尚未升級至 v35.0.0 或更新版本，就必須通過本機用戶端設定驗證。
• login_customer_id (googleads.properties 中的 loginCustomerId，GOOGLE_ADS_LOGIN_CUSTOMER_ID)：用來存取客戶帳戶的管理員帳戶 ID。請參閱登入客戶 ID 說明文件。
• linked_customer_id (linkedCustomerId in googleads.properties, GOOGLE_ADS_LINKED_CUSTOMER_ID)：已連結的客戶 ID。
• service_address (serviceAddress in googleads.properties, GOOGLE_ADS_ENDPOINT)：Google Ads API 服務位址網址 (預設為 "https://googleads.googleapis.com")。
• user_agent (userAgent in googleads.properties, GOOGLE_ADS_PERL_USER_AGENT)：HTTP 請求中包含的自訂 User-Agent 標頭前置字元。
• proxy (proxy in googleads.properties, GOOGLE_ADS_PERL_PROXY)：用於網際網路連線的 Proxy 伺服器網址。
• version (Client->new 或 set_version)：要使用的 Google Ads API 版本模組 (預設為 "V25")。
• die_on_faults (Client->new 或 set_die_on_faults)：設為 1，讓服務方法在發生 API 錯誤時，呼叫 die() 並傳回原始回應酬載，而不是傳回 Google::Ads::GoogleAds::GoogleAdsException 物件 (預設為 0)。
• http_timeout (Client->new 或 set_http_timeout)：HTTP 逾時時間 (以秒為單位)，預設為 3600。
• http_retry_timing (Client->new 或 set_http_retry_timing)：暫停重試間隔 (以秒為單位)，適用於暫時性 HTTP 503 和 504 錯誤 (預設為 "5,10,15")。