Authentication

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

PHP 库可按如下方式配置：

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withJsonKeyFilePath('INSERT_PATH_TO_JSON_KEY_FILE_HERE')
    // Optional in v32.1.0 and later (defaults to
    // 'https://www.googleapis.com/auth/adwords').
    ->withScopes('https://www.googleapis.com/auth/adwords')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

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

单用户身份验证流程

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

  1. 向单个用户授予对所有要使用 Google Ads API 管理的账号的访问权限。一种常见的方法是向用户授予 Google Ads API 经理账号的访问权限，并关联该经理账号下的所有 Google Ads 账号。
  2. 然后，该用户运行 GenerateUserCredentials 等命令行工具，以授权您的应用代表其管理所有 Google Ads 账号。

可以使用用户的 OAuth 2.0 凭证初始化该库，如下所示：

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

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

多用户身份验证流程

如果您的应用允许用户登录并授权您的应用代表其管理 Google Ads 账号，建议您采用此工作流程。您的应用会为每个经过身份验证的用户会话动态构建和管理 OAuth 2.0 用户凭据。可以使用已登录用户的凭据初始化该库，如下所示：

// Construct credentials dynamically per authenticated user session.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken($userRefreshToken)
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId($userLoginCustomerId)
    ->build();

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

应用默认凭据

PHP 客户端库还支持使用应用默认凭证 (ADC) 进行身份验证。如果未在 OAuth2TokenBuilder 上设置应用模式（clientId、clientSecret、refreshToken）或服务账号模式（jsonKeyFilePath）凭据，则调用 build() 会自动回退到应用默认凭证：

$oAuth2Credential = (new OAuth2TokenBuilder())->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

管理多个账号

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

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