驗證與授權

如同其他 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 (在某些情況下)。

開發人員權杖：

開發人員符記會連結至管理員帳戶，您可以在 Google Ads 網頁介面中找到。

雖然開發人員符記會連結至管理員帳戶，但不會提供該帳戶的存取權。開發人員權杖授予的是一般 API 存取權，帳戶層級存取權則是透過 OAuth 2.0 設定。

在用戶端程式庫中，開發人員權杖是在 ads.properties 檔案中以 api.googleads.developerToken 金鑰指定。

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=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

單一使用者驗證流程

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

  1. 授予單一使用者存取所有待管理帳戶的權限，以便透過 Google Ads API 管理這些帳戶。常見的做法是將使用者新增至 Google Ads API 管理員帳戶，並連結該管理員帳戶下的所有 Google Ads 帳戶。
  2. 使用者執行 gcloud 等指令列工具或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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

多使用者驗證流程

如果您的應用程式允許使用者登入，並授權應用程式代為管理 Google Ads 帳戶，建議採用這個工作流程。「GenerateUserCredentials」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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_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。使用應用程式預設憑證時，不應設定用戶端 ID、用戶端密鑰和更新權杖。