身份验证与授权

与其他 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. get_account_hierarchy 代码示例展示了如何检索 Google Ads 经理账号下的所有账号的列表。
  2. list_accessible_customers 代码示例展示了如何检索用户有权直接访问的所有账号的列表。然后，这些账号可用作 login_customer_id 设置的有效值。