身份验证与授权

与其他 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 账号。

以下是在 Perl 客户端库中使用服务账号通过您自己的凭据设置 OAuth2 以进行 API 访问的方法：

  1. 创建 OAuth2 凭据：

    按照说明生成服务账号和 JSON 密钥 文件。

  2. 设置客户端库：

    在配置中设置私钥 JSON 路径（如果使用 Google Workspace 全网域委托，则为可选的 impersonatedEmail）。如果您使用的是 googleads.properties 文件，请添加以下内容：

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
# Optional unless using Google Workspace domain-wide delegation:
impersonatedEmail=IMPERSONATED_EMAIL
loginCustomerId=LOGIN_CUSTOMER_ID

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=\
IMPERSONATED_EMAIL
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

单用户身份验证工作流

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

  1. 向单个用户授予对所有要使用 Google Ads API 管理的账号的访问权限。一种常见方法是向用户授予对 Google Ads API 经理账号的访问权限，并将该经理账号下的所有 Google Ads 账号关联起来。
  2. 用户运行 generate_user_credentials.pl代码示例 以授权您的应用代表他们管理其所有 Google Ads 账号。

以下步骤将运行一个互动式代码示例，然后需要您提供输入。

  1. 在终端中，运行 generate_user_credentials.pl 示例在 examples 目录中。您可以在运行之前修改示例中的 INSERT_XXX_HERE 值，也可以使用命令行实参 -client_id 作为客户端 ID，使用 -client_secret 作为客户端密钥。

    perl generate_user_credentials.pl \
  -client_id OAUTH_CLIENT_ID \
  -client_secret OAUTH_CLIENT_SECRET

  2. 此代码示例会提示您访问一个网址，您必须在该网址中授权应用代表您访问您的 Google Ads 账号。

    Paste this url in your browser:
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline...

    在私密浏览器会话或无痕式窗口中访问该网址。使用您用于访问 Google Ads 的 Google 账号登录。通常，这是一个电子邮件账号，该账号有权访问 Google Ads 经理账号，而该经理账号的账号层次结构中包含您需要管理的所有账号。在 OAuth 2.0 权限请求页面上，点击继续 。

    OAuth 2.0 权限请求页面

    您将被重定向到一个页面，其中会显示一条消息，表明授权成功。

    Authorization code was successfully retrieved.

  3. 返回到您运行代码示例的控制台。您会看到，代码示例已完成，并显示了您的刷新令牌和一些说明，以及您需要按照这些说明配置客户端库：

    Replace the following keys and values in your googleads.properties
configuration file:

clientId=***********************apps.googleusercontent.com
clientSecret=****
refreshToken=****

  4. 按 Ctrl + C 终止该进程。然后，将生成的刷新令牌以及客户端 ID 和客户端密钥复制到 googleads.properties 文件中，或者将其保存到其他位置，以便在运行时实例化库时使用。

您可以通过在 googleads.properties 中设置以下内容，使用用户的 OAuth 2.0 凭据初始化库：

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

或者，您也可以使用环境变量：

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

多用户身份验证工作流

如果您的应用允许用户登录并授权您的应用代表他们管理其 Google Ads 账号，建议使用此工作流。您的应用会构建和管理 OAuth 2.0 用户凭据。

对于 Perl，您通常会实现 Web 应用流程，其中您的应用会处理 OAuth 2.0 重定向和令牌管理。用户通过您的应用进行身份验证，您的应用会存储并使用用户的刷新令牌来代表他们进行 API 调用。

使用所获凭据的配置与单用户身份验证工作流的配置相同：

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

或者，您也可以使用环境变量：

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

如果我的用户管理多个账号，该怎么办？

用户通常会管理多个 Google Ads 账号，无论是通过直接访问账号，还是通过 Google Ads 经理账号。Perl 客户端库提供了示例，说明了如何处理此类情况：

  1. The get_account_hierarchy.pl 示例展示了 如何检索 Google Ads 经理账号下的所有账号的列表。
  2. The list_accessible_customers.pl 示例 展示了如何检索用户可以直接访问的所有账号的列表 。然后，这些账号可以用作 googleads.properties 文件中的 loginCustomerId 设置或 GOOGLE_ADS_LOGIN_CUSTOMER_ID 环境变量的有效值。