驗證與授權

如同其他 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 設定。