身份验证和授权

与其他 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 路径。如果您使用的是 googleads.properties 文件，请添加以下内容：

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH

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

单用户身份验证流程

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

  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 {client_id} -client_secret {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&client_id=...

    在无痕浏览会话或无痕式窗口中访问相应网址。 使用您用于访问 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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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 文件中的 LoginCustomerId 设置或 GOOGLE_ADS_LOGIN_CUSTOMER_ID 环境变量的有效值。