驗證及授權

與其他 Google API 相同，Google Ads API 也使用 OAuth 2.0 通訊協定進行驗證及授權。OAuth 2.0 可讓 Google Ads API 用戶端應用程式存取使用者的 Google Ads 帳戶，不必處理或儲存使用者的登入資訊。

本指南說明如何使用三種最常見的 OAuth 2.0 流程，設定 Java 用戶端程式庫進行 Google Ads API 驗證，並說明必要憑證。

如要深入瞭解 Google Ads API 存取模式，請參閱 Google Ads 存取模式指南。

憑證

如要存取 Google Ads API，您需要 OAuth 2.0 憑證，有時還需要登入客戶 ID。

OAuth 2.0 憑證

如要以有權存取 Google Ads 帳戶的 Google 帳戶使用者身分授權，您必須提供一組 OAuth 2.0 憑證。視使用的 OAuth 2.0 流程而定，所需的憑證類型也會有所不同。

這個程式庫支援三種流程：

  • 服務帳戶流程
  • 單一使用者驗證流程
  • 多使用者驗證流程

如要瞭解 Google Ads API OAuth 流程的詳細資料，請參閱 OAuth 總覽，並按照最符合您需求的流程操作說明，取得必要憑證。

登入客戶 ID

如有需要，請指定提供放送帳戶存取權的管理員帳戶客戶 ID。如果透過管理員帳戶存取客戶帳戶，則必須指定這項資訊。不必指定客戶 ID 路徑上的所有管理員帳戶，只要指定用於存取權限的最上層管理員 ID 即可。詳情請參閱相關說明文件。

在用戶端程式庫中，登入客戶 ID 是由 ads.properties 檔案中的 api.googleads.loginCustomerId 鍵指定。

設定

您可以透過 ads.properties 檔案、環境變數或以程式輔助方式設定用戶端程式庫。本指南著重於使用ads.properties檔案。如要瞭解所有選項的詳細資料，請參閱設定指南。

如果使用 ads.properties 檔案，請將其放在主目錄中： ~/ads.properties。

OAuth 工作流程

使用 Google Ads API 時，通常會用到三種工作流程。

服務帳戶流程

如果工作流程不需要任何人為互動，建議採用這個工作流程。這項工作流程需要設定步驟，使用者必須將服務帳戶新增至 Google Ads 帳戶。應用程式隨後就能使用服務帳戶的憑證，管理使用者的 Google Ads 帳戶。

取得私密金鑰 JSON 檔案後，請在 ads.properties 檔案中新增下列內容：

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

如要瞭解詳情，請參閱服務帳戶工作流程指南。

單一使用者驗證流程

如果無法使用服務帳戶，可以採用這個工作流程。這項工作流程需要完成兩個設定步驟：

  1. 使用 Google Ads API 授權單一使用者存取所有要管理的帳戶。常見的做法是授予使用者 Google Ads API 管理員帳戶的存取權，並連結該管理員帳戶下的所有目標 Google Ads 帳戶。
  2. 使用者執行 gcloud CLI 等指令列工具或GenerateUserCredentials程式碼範例，授權應用程式代表他們管理所有 Google Ads 帳戶。

取得這些憑證後，請在 ads.properties 檔案中新增下列內容：

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

詳情請參閱單一使用者驗證工作流程指南。

多使用者驗證流程

如果您的應用程式允許使用者登入，並授權應用程式代表他們管理 Google Ads 帳戶，建議採用這個工作流程。這個 GenerateUserCredentials程式碼範例是指令列工具，說明如何在執行階段取得使用者驗證，以便代為管理 Google Ads 帳戶。您可以參考這個程式碼範例，建構需要使用者驗證的電腦或網頁應用程式。

如果是多使用者應用程式，請將應用程式的 OAuth 2.0 用戶端 ID 和用戶端密鑰儲存在 ads.properties (或其他設定儲存空間)，同時將每個使用者的更新權杖安全地儲存在應用程式資料庫中，並在建構 UserCredentials 和 GoogleAdsClient 時，以程式輔助方式在執行階段傳遞：

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

詳情請參閱多使用者驗證工作流程指南。

管理多個帳戶

使用者通常會管理多個 Google Ads 帳戶，可能是直接存取帳戶，也可能是透過 Google Ads 管理員帳戶。Java 用戶端程式庫提供下列程式碼範例，說明如何處理這類情況：

  1. GetAccountHierarchy 程式碼範例說明如何擷取 Google Ads 管理員帳戶下的所有帳戶清單。
  2. ListAccessibleCustomers 程式碼範例說明如何擷取使用者可直接存取的所有帳戶清單。這些帳戶隨後可用於 loginCustomerId 設定的有效值。

應用程式預設憑證

Java 用戶端程式庫也支援使用應用程式預設憑證進行驗證。

如果您要進行本機開發，或是針對不同的 Google API 進行開發，這項功能就特別實用，因為只要憑證可以存取必要的 OAuth 2.0 範圍，您就能重複使用相同的憑證。

如果是 Google Ads API，請確認應用程式預設憑證可以存取 https://www.googleapis.com/auth/adwords OAuth 2.0 範圍。

如要使用應用程式預設憑證，請在 ads.properties 檔案中將 api.googleads.useApplicationDefaultCredentials 選項設為 true (或在 GoogleAdsClient.newBuilder() 上呼叫 .enableApplicationDefaultCredentials())。使用應用程式預設憑證時，不應設定用戶端 ID、用戶端密鑰和更新權杖。