配置

您可以使用 YAML 文件、环境变量、YAML 字符串或 dict 配置 Python 客户端库。

身份验证配置

您可以通过多种方式管理访问 Google Ads API 所需的 OAuth 凭据。您选择的方法会影响您使用的配置字段。如需了解详情，请参阅身份验证指南。

使用 YAML 文件进行配置

您可以指定在初始化客户端时使用的 YAML 文件，该文件包含向 Google Ads API 发出请求所需的必要信息。当使用 load_from_storage 方法初始化客户端时，系统会访问此文件。生成此文件的最简单方法是从 GitHub 代码库中复制 google-ads.yaml 示例，然后对其进行修改，以包含您的凭据，包括刷新令牌、客户端 ID 和客户端 Secret。

如果您未提供路径，该库会在 $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 网域范围的委托时要模拟的账号的可选电子邮件地址。

库行为

这些字段决定了库的行为：

请求级配置

  • linked_customer_id：请参阅关联客户 ID 文档。
  • login_customer_id：请参阅 login-customer-id 文档。
  • endpoint：可选的备用 Google Ads API 端点地址。
  • ads_assistant：Google Ads API 助理标头的可选标识符。

环境变量

如需使用环境变量配置库，请使用以下内容：

  • 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：用于定义不同类型日志记录器的字典，其中包括处理程序和日志级别。