身份验证和授权

与其他 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 账号。Python 库的配置如下：

• 如果使用 google-ads.yaml 文件或 YAML 字符串，请在配置中添加以下内容，以设置本地环境中私钥 JSON 文件的路径：

  json_key_file_path: JSON_KEY_FILE_PATH
  

  然后调用 load_from_storage 或 load_from_string 方法：

  from google.ads.googleads.client import GoogleAdsClient
  client = GoogleAdsClient.load_from_storage()
  

• 如果您使用 dict 配置库，请添加以下键值对并调用 load_from_dict 方法，传入配置 dict：

  from google.ads.googleads.client import GoogleAdsClient
  
  configuration = {
    # ...
    "json_key_file_path": JSON_KEY_FILE_PATH
    # ...
  }
  
  client = GoogleAdsClient.load_from_dict(configuration)
  

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

  export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
  

  然后调用 load_from_env 方法：

  from google.ads.googleads.client import GoogleAdsClient
  client = GoogleAdsClient.load_from_env()
    ```
  

如果上述任何配置方法中都存在 json_key_file_path 配置选项，并且 use_application_default_credentials 选项为 False 或未设置，则该库将自动使用服务账号流程进行授权。

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

单用户身份验证流程

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

1. 向单个用户授予使用 Google Ads API 管理的所有账号的访问权限。一种常见的方法是向用户授予 Google Ads API 经理账号的访问权限，并关联该经理账号下的所有 Google Ads 账号。

2. 用户运行 gcloud CLI 或 generate_user_credentials 代码示例等工具，以授权您的应用代表其管理其所有 Google Ads 账号。

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

如果使用 gcloud CLI 工具（推荐）

1. 按照生成凭据文档中的说明在本地环境中设置应用默认凭据 (ADC)。

2. 将以下配置添加到您的 google-ads.yaml 或 YAML 字符串中：

   use_application_default_credentials: true
   

   然后，调用 load_from_storage 或 load_from_string 方法：

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_storage()
   

   如果您使用 dict 配置库，请添加以下键值对并调用 load_from_dict 方法：

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
     # ...
     "use_account_default_credentials": True
     # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

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

   export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true
   

   然后调用 load_from_env 方法：

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_env()
   

如果直接处理 OAuth 令牌

1. 按照步骤设置控制台项目，然后下载包含项目客户端 ID 和客户端密钥的 JSON 文件。

2. 将 Python 客户端库克隆到您的机器，然后切换到其目录：

   $ git clone https://github.com/googleads/google-ads-python.git
   $ cd google-ads-python
   

3. 执行该示例，并提供在第 1 步中下载的 JSON 文件的绝对路径：

   $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON
   

   完成后，系统会将刷新令牌打印到控制台。复制并保存此网址，以供下一步使用。

4. 通过将以下设置添加到您选择的配置中来配置库：

   将以下配置添加到您的 google-ads.yaml 或 YAML 字符串中：

   client_id: INSERT_OAUTH2_CLIENT_ID_HERE
   client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
   refresh_token: INSERT_REFRESH_TOKEN_HERE
   

   然后，调用 load_from_storage 或 load_from_string 方法：

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_storage()
   

   如果您使用 dict 配置库，请添加以下键值对并调用 load_from_dict 方法：

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
     # ...
     "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
     "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
     "refresh_token": INSERT_REFRESH_TOKEN_HERE
     # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

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

   export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
   export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
   export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE
   

   然后调用 load_from_env 方法：

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_env()
   

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

多用户身份验证流程

如果您的应用允许用户登录并授权您的应用代表其管理 Google Ads 账号，建议采用此工作流程。您的应用构建并管理 OAuth 2.0 用户凭据。可以使用用户的凭据初始化该库，如下所示。此示例假设您的应用在运行时通过执行授权流程或从数据存储区加载凭据来获取凭据：

dict 是在运行时获取凭据时使用的最简单配置机制：

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

手动身份验证

您可以使用任何方法生成身份验证凭据，并通过直接实例化客户端类手动将其提供给 GoogleAdsClient。假设您创建的凭据对象是 google.auth.credentials.Credentials 的实例，您可以按如下方式传入该对象：

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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

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

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