身份验证与授权

与其他 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. 在终端中，运行 examples 目录中的 generate_user_credentials.pl 示例。您可以在运行前修改示例中的 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. get_account_hierarchy.pl 示例展示了如何检索 Google Ads 经理账号下的所有账号的列表。
  2. list_accessible_customers.pl 示例展示了如何检索用户拥有直接访问权限的所有账号的列表。然后，这些账号可用作 googleads.properties 文件或 GOOGLE_ADS_LOGIN_CUSTOMER_ID 环境变量中 loginCustomerId 设置的有效值。