身份验证与授权

与 Google 的其他 API 一样，Google Ads API 使用 OAuth 2.0 协议进行身份验证和授权。OAuth 2.0 可让您的 Google Ads API 客户端应用访问用户的 Google Ads 账号，而无需处理或存储用户的登录信息。

了解 Google Ads 访问权限模型

如需高效使用 Google Ads API，请了解 Google Ads 访问权限模型的工作原理。请参阅 Google Ads 访问权限模型指南。

OAuth 工作流

使用 Google Ads API 时，有三种常见的工作流。

服务账号工作流

如果您的工作流不需要任何人工互动，建议使用此工作流。此工作流需要一个配置步骤，即用户将其 服务账号添加到其 Google Ads 账号。然后，应用可以使用服务账号的凭据来管理用户的 Google Ads 账号。Python 库的配置如下：

  • 如果使用 google-ads.yaml 文件或 YAML 字符串，请将以下内容添加到您的配置中，以设置本地环境中私钥 JSON 文件的路径（如果使用网域级委托，还可以选择添加 impersonated_email）：

    json_key_file_path: JSON_KEY_FILE_PATH
# Optional: only set if using Google Workspace domain-wide delegation:
# impersonated_email: IMPERSONATED_EMAIL

    然后调用 load_from_storage 或 load_from_string 方法：

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

  • 如果您使用 dict 配置库，请添加以下 键值对并调用 load_from_dict 方法，传入 配置 dict：

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "json_key_file_path": JSON_KEY_FILE_PATH,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

  • 如果您使用环境变量，请将以下内容添加到您的 bash 配置或环境中：

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    然后调用 load_from_env 方法：

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

如果这些配置方法中的任何一种都存在 json_key_file_path 配置选项，并且 use_application_default_credentials 选项为 False 或未设置，并且 OAuth 用户凭据键（client_id、client_secret 和 refresh_token）未设置或被注释掉，则库会自动使用服务账号工作流进行授权。

如需了解详情，请参阅服务账号工作流指南。

单用户身份验证工作流

如果您无法使用服务账号，则可以使用此工作流。此工作流需要两个配置步骤：

  1. 向单个用户授予对所有要使用 Google Ads API 管理的账号的访问权限。一种常见的方法是向用户授予对 Google Ads API 经理账号的访问权限，并关联该经理账号下的所有 Google Ads 账号。

  2. 用户运行 gcloud CLI 或 generate_user_credentials代码示例等工具，以 授权您的应用代表他们管理其所有 Google Ads 账号。

可以使用用户的 OAuth 2.0 凭据初始化库，如下所示：

如果使用 gcloud CLI 工具（推荐）

  1. 按照生成凭据文档中的说明，在本地环境中设置 应用默认凭据 (ADC)。

  2. 将以下配置添加到您的 google-ads.yaml 或 YAML 字符串：

    use_application_default_credentials: true

    然后调用 load_from_storage 或 load_from_string 方法：

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    如果您使用 dict 配置库，请添加以下 键值对并调用 load_from_dict 方法：

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "use_application_default_credentials": True,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    如果您使用环境变量，请将以下内容添加到您的 bash 配置或环境中：

    export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS=true

    然后调用 load_from_env 方法：

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

如果直接处理 OAuth 令牌

  1. 按照相关步骤设置控制台项目并 下载包含项目客户端 ID 和客户端 密钥的 JSON 文件。

  2. 将 Python 客户端库克隆到您的机器，然后进入其目录：

    git clone https://github.com/googleads/google-ads-python.git
cd google-ads-python

  3. 执行示例，提供在第 1 步中下载的 JSON 文件的绝对路径：

    python examples/authentication/generate_user_credentials.py \
    -c PATH_TO_CREDENTIALS_JSON

    完成后，系统会在控制台中输出刷新令牌。复制并保存该令牌，以供下一步使用。

  4. 通过将以下设置添加到您选择的配置中来配置库：

    将以下配置添加到您的 google-ads.yaml 或 YAML 字符串：

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    然后调用 load_from_storage 或 load_from_string 方法：

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    如果您使用 dict 配置库，请添加以下 键值对并调用 load_from_dict 方法：

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": INSERT_OAUTH2_CLIENT_ID_HERE,
    "client_secret": (
        INSERT_OAUTH2_CLIENT_SECRET_HERE
    ),
    "refresh_token": INSERT_REFRESH_TOKEN_HERE,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    如果您使用环境变量，请将以下内容添加到您的 bash 配置或环境中：

    export GOOGLE_ADS_CLIENT_ID=\
INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=\
INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=\
INSERT_REFRESH_TOKEN_HERE

    然后调用 load_from_env 方法：

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

如需了解详情，请参阅单用户身份验证工作流指南以 了解更多。

多用户身份验证工作流

如果您的应用允许用户登录并授权您的应用代表他们管理其 Google Ads 账号，建议使用此工作流。您的应用会构建和管理 OAuth 2.0 用户凭据。可以使用用户的凭据初始化库，如下所示。此方法假定您的应用在运行时获取凭据，方法是执行授权流程或从数据存储区加载凭据：

在运行时获取凭据时，dict 是最简单的配置机制：

from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": client_id,
    "client_secret": client_secret,
    "refresh_token": refresh_token,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

如需了解详情，请参阅多用户身份验证工作流指南以 了解更多。

手动身份验证

您可以使用任何方法生成身份验证凭据，并通过直接实例化客户端类来手动将这些凭据提供给 GoogleAdsClient。假设您创建的凭据对象是 google.auth.credentials.Credentials 的实例，您可以按如下方式传入该对象：

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`.
credentials, _ = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
    credentials=credentials,
    use_proto_plus=True,
)

管理多个账号

用户通常会管理多个 Google Ads 账号，可以通过直接访问账号，也可以通过 Google Ads 经理账号进行管理。Python 客户端库提供了以下代码示例，说明了如何处理此类情况：

  1. The get_account_hierarchy 代码示例 展示了如何检索 Google Ads 经理 账号下的所有账号的列表。
  2. list_accessible_customers code 示例展示了如何检索用户可以直接访问的所有账号的列表。然后，这些账号可用作 login_customer_id 设置的有效值。