設定

您可以使用 YAML 檔案、環境變數、YAML 字串或 dict 設定 Python 用戶端程式庫。

驗證設定

管理存取 Google Ads API 所需 OAuth 憑證的方法有很多種。您選擇的方法會影響使用的設定欄位。詳情請參閱驗證指南。

使用 YAML 檔案設定

初始化用戶端時，您可以指定要使用的 YAML 檔案，其中包含向 Google Ads API 提出要求時所需的資訊。使用 load_from_storage 方法初始化用戶端時，系統會存取這個檔案。產生這個檔案最簡單的方法，就是從 GitHub 存放區複製 google-ads.yaml 範例，然後修改範例，加入您的憑證，包括更新權杖、用戶端 ID 和用戶端密鑰。

如未提供路徑，程式庫會在 $HOME 目錄中尋找檔案：

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

如要指定 google-ads.yaml 檔案所在位置，可以在呼叫方法時，將路徑做為字串傳遞至方法：

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

您也可以定義特定環境變數來指定路徑：

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

如果同時提供這兩個值 (路徑傳遞至方法，且存在環境變數)，程式庫會優先處理傳遞至方法的路徑。

使用環境變數進行設定

您可以將所有用戶端設定儲存為環境變數，並在使用用戶端的 load_from_env 方法時讀取這些變數。環境變數的名稱應與 google-ads.yaml 檔案中定義的名稱相同，但必須全部大寫，並加上 GOOGLE_ADS_ 命名空間前置字元。舉例來說，client_id 應儲存為 GOOGLE_ADS_CLIENT_ID。

環境變數通常是在 Bash 設定檔中定義，例如 $HOME 目錄中的 .bashrc 或 .bash_profile 檔案。也可以使用指令列定義。

以下是在終端機中使用 .bashrc 檔案定義環境變數的基本步驟：

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

您也可以直接從指令列，在終端機執行個體中設定環境變數：

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

load_from_env 方法會從 Python 內建 os 模組的 environ 屬性載入設定資料。例如： os.environ["GOOGLE_ADS_CLIENT_ID"]

以下範例說明如何使用環境變數中的設定，初始化用戶端例項：

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

如要透過環境變數設定 logging，設定值必須是符合範例 google-ads.yaml 設定檔中 YAML 金鑰結構的 JSON 物件。

以下是使用 .bashrc 檔案設定這項功能的範例：

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

重要事項：如果在呼叫 load_from_env 方法時設定了 GOOGLE_ADS_CONFIGURATION_FILE_PATH 環境變數，系統會從指定路徑的 google-ads.yaml 檔案擷取設定值，而不是從先前所述的環境變數擷取。

使用 YAML 字串設定

如果已將 YAML 檔案讀取到記憶體中，您可以在初始化時直接提供給用戶端。如要這麼做，請使用 load_from_string 方法：

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

使用 dict 進行設定

您可以將 dict 直接傳遞至 load_from_dict 方法。例如：

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

設定欄位

用戶端程式庫設定支援下列欄位。

驗證

請視您使用的驗證方法，只使用其中一組欄位：

  • 單一使用者，使用應用程式預設憑證 (說明文件)
    • use_application_default_credentials：程式庫是否應使用應用程式預設憑證 (ADC) 進行驗證 (google-ads v28.3.0 以上版本支援)。
  • 使用 OAuth 權杖的單一使用者 (說明文件)
    • client_id：您的 OAuth 用戶端 ID。
    • client_secret：您的 OAuth 用戶端密鑰。
    • refresh_token：您的 OAuth 更新權杖。
  • 服務帳戶 (說明文件)
    • json_key_file_path：本機私密金鑰檔案的路徑。用於透過服務帳戶進行驗證。
    • impersonated_email：使用 Google Workspace 網域範圍委派時，要模擬的帳戶電子郵件地址 (選用)。

程式庫行為

這些欄位會決定程式庫的行為：

要求層級設定

環境變數

如要使用環境變數設定程式庫，請使用下列指令：

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (支援 v28.3.0 以上版本)

記錄檔設定

記錄檔欄位 (即 logging 設定欄位下方的欄位) 是直接從 logging.config 內建模組衍生而來，因為程式庫會將 logging 命名空間下的所有欄位直接傳遞至 logging.config.dictConfig 方法。詳情請參閱記錄指南。

  • version：代表結構定義版本的整數值。
  • disable_existing_loggers：是否應停用應用程式中其他位置設定的記錄器。
  • formatters：定義不同類型格式器的字典。
  • handlers：定義不同處理常式的字典，可控管記錄檔的寫入位置和使用的格式化工具。
  • loggers：定義不同記錄器類型的字典，包括處理常式和記錄層級。