身份验证和授权

与其他 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 账号。如需配置此设置，请在 Google Cloud 控制台中创建并下载 JSON 密钥文件，然后将 google_ads_config.rb 复制到您的主目录，并对其进行修改以指定服务账号密钥文件位置和要模拟的用户的电子邮件地址：

  # You can also authenticate using a service account. If "keyfile" is
  # specified below, then service account authentication will be assumed and
  # the above authentication fields ignored. Read more about service account
  # authentication here:
  # https://developers.google.com/google-ads/api/docs/oauth/service-accounts
  # c.keyfile = 'path/to/keyfile.json'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

如果您不想将此信息存储在文件中，而更愿意使用环境变量，则可以分别设置 GOOGLE_ADS_JSON_KEY_FILE_PATH 和 GOOGLE_ADS_IMPERSONATED_EMAIL。

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

您也可以在运行时以编程方式传递信息，方法是使用 googleauth gem 从服务账号 JSON 文件创建凭据：

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file
key_file = "/path/to/your/service-account-key.json"

# Define the scopes needed for the Google Ads API
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials
credentials = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

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

单用户身份验证流程

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

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

您可以为 Ruby 配置 OAuth 2.0 凭据，方法是将 google_ads_config.rb 文件复制到您的主目录，然后修改该文件以添加您的开发者令牌、客户端 ID、客户端密钥和刷新令牌：

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

如果客户端在实例化时未提供任何实参，则会自动从主目录读取配置文件：

client = Google::Ads::GoogleAds::GoogleAdsClient.new

或者，如果您希望将文件存储在其他位置，可以通过传递此文件的存储路径来实例化客户端：

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

如果您不想将此信息存储在文件中，而更愿意使用环境变量，则可以设置每个变量：

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

您还可以在运行时以编程方式传递信息：

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

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

多用户身份验证流程

如果您的应用允许用户登录并授权您的应用代表其管理 Google Ads 账号，建议采用此工作流程。您的应用构建并管理 OAuth 2.0 用户凭据。此工作流的配置方式与单用户流程类似，但还需指定 login_customer_id。

我们建议您使用配置文件。将 google_ads_config.rb 文件复制到您的主目录，并对其进行修改，以包含您的开发者令牌、客户端 ID、客户端密钥、刷新令牌和客户 ID：

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

  # Required for manager accounts only: Specify the login customer ID used to
  # authenticate API calls. This will be the customer ID of the authenticated
  # manager account. If you need to use different values for this field, then
  # make sure fetch a new copy of the service after each time you change the
  # value.
  # c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

如果客户端在实例化时未提供任何实参，则会自动从主目录读取配置文件：

client = Google::Ads::GoogleAds::GoogleAdsClient.new

或者，如果您希望将文件存储在其他位置，可以通过传递此文件的存储路径来实例化客户端：

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

如果您不想将此信息存储在文件中，而更愿意使用环境变量，则可以设置每个变量：

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

您还可以在运行时以编程方式传递信息：

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

如需了解详情，请参阅多用户身份验证工作流指南。Ruby 客户端库包含一个代码示例供您参考。GenerateUserCredentials 是一个命令行代码示例，用于说明如何在运行时获取用户身份验证信息，以便代表用户管理其 Google Ads 账号。您可以将此代码示例用作参考，来构建需要进行用户身份验证的桌面应用。

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

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

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

应用默认凭据

Ruby 客户端库还支持使用应用默认凭据 (ADC) 进行身份验证。借助此功能，您可以为应用设置默认凭据，而无需在应用配置中配置 OAuth 2.0 信息。

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

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

如需使用应用默认凭据，我们建议使用 Google Cloud 命令行工具并针对 ADC 进行身份验证：

gcloud auth application-default login

此命令将打开一个网络浏览器，以完成 Google 账号的身份验证流程。获得授权后，它会将凭据存储在标准位置。然后，您需要更新应用以使用 ADC。

我们建议您使用配置文件。将 google_ads_config.rb 文件复制到您的主目录，然后添加您的开发者令牌并将 use_application_default_credentials 设置为 true：

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # You can also authenticate using Application Default Credentials (ADC)
  # To understand how ADC discovers credentials in a given environment,
  # see: https://developers.google.com/identity/protocols/application-default-credentials.
  c.use_application_default_credentials = true

如果您不想将此信息存储在文件中，而更愿意使用环境变量，则可以设置 GOOGLE_ADS_DEVELOPER_TOKEN 和 GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS：

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

您还可以在运行时以编程方式传递信息。在 Ruby 代码中初始化客户端时，请勿提供明确的 OAuth2 凭据。该库将自动检测并使用 Google Cloud 命令行工具设置的凭据。您仍需指定开发者令牌。

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = "YOUR_LOGIN_CUSTOMER_ID"

  # Do NOT include oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

如需详细了解可用于配置 Ruby 客户端库的选项，请参阅配置页面。