Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

身份验证与授权

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

本指南介绍了如何使用三种最常见的 OAuth 2.0 流程配置 Java 客户端库以进行 Google Ads API 身份验证，并说明了所需的凭据。

如需深入了解 Google Ads API 访问模式，请参阅 Google Ads 访问模式指南。

凭证

访问 Google Ads API 需要 OAuth 2.0 凭据，在某些情况下还需要登录客户 ID。

OAuth 2.0 凭证

如需以有权访问 Google Ads 账号的 Google 账号用户身份进行授权，您必须提供一组 OAuth 2.0 凭据。所需的凭据类型因所使用的 OAuth 2.0 流程而异。

该库支持以下三种流程：

服务账号流程
单用户身份验证流程
多用户身份验证流程

如需详细了解 Google Ads API OAuth 流程，请参阅 OAuth 概览，然后按照最符合您需求的流程说明操作，以获取所需的凭据。

（可选）指定可访问广告投放账号的经理账号的客户 ID。如果您是通过经理账号访问客户账号，则必须指定此值。您无需指定客户 ID 路径中的所有经理账号，只需指定您用于访问权限的最顶层经理账号 ID 即可。如需了解详情，请参阅相关文档。

在客户端库中，登录客户 ID 由 ads.properties 文件中的 api.googleads.loginCustomerId 键指定。

配置

您可以使用 ads.properties 文件、环境变量或以编程方式配置客户端库。本指南重点介绍如何使用 ads.properties 文件。如需详细了解所有选项，请参阅配置指南。

如果您使用 ads.properties 文件，请将其放在主目录中：~/ads.properties。

OAuth 工作流

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

服务账号流程

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

获得私钥 JSON 文件后，请将以下内容添加到 ads.properties 文件中：

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

单用户身份验证流程

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

向单个用户授予对所有要使用 Google Ads API 管理的账号的访问权限。一种常见的方法是向用户授予对 Google Ads API 经理账号的访问权限，并将所有目标 Google Ads 账号关联到该经理账号下。
用户运行 gcloud CLI 等命令行工具或GenerateUserCredentials 代码示例，以授权您的应用代表他们管理其所有 Google Ads 账号。

获得这些凭据后，请将以下内容添加到 ads.properties 文件中：

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

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

多用户身份验证流程

如果您的应用允许用户登录并授权您的应用代表其管理 Google Ads 账号，建议采用此工作流程。GenerateUserCredentials 代码示例是一个命令行工具，用于演示如何在运行时获取用户身份验证，以便代表用户管理其 Google Ads 账号。您可以参考此代码示例来构建需要进行用户身份验证的桌面应用或 Web 应用。

对于多用户应用，请将应用的 OAuth 2.0 客户端 ID 和客户端密钥存储在 ads.properties（或其他配置存储区）中，同时将每个最终用户的刷新令牌安全地存储在应用数据库中，并在构建 UserCredentials 和 GoogleAdsClient 时以编程方式在运行时传递该令牌：

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

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

管理多个账号

用户通常会直接访问账号或通过 Google Ads 经理账号来管理多个 Google Ads 账号。Java 客户端库提供了以下代码示例，展示了如何处理此类情况：

GetAccountHierarchy 代码示例展示了如何检索 Google Ads 经理账号下的所有账号的列表。
ListAccessibleCustomers 代码示例展示了如何检索用户可直接访问的所有账号的列表。然后，这些账号可用作 loginCustomerId 设置的有效值。

应用默认凭据

Java 客户端库还支持使用应用默认凭证进行身份验证。

这对于本地开发或针对不同的 Google API 进行开发特别有用，因为您可以重复使用相同的凭据，前提是这些凭据可以访问所需的 OAuth 2.0 范围。

对于 Google Ads API，请确保您的应用默认凭据可以访问 https://www.googleapis.com/auth/adwords OAuth 2.0 范围。

如需使用应用默认凭证，请在 ads.properties 文件中将 api.googleads.useApplicationDefaultCredentials 选项设置为 true（或对 GoogleAdsClient.newBuilder() 调用 .enableApplicationDefaultCredentials()）。使用应用默认凭证时，不应设置客户端 ID、客户端密钥和刷新令牌。