驗證與授權

如同其他 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」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 用戶端程式庫的可用設定選項，請參閱設定頁面。