Authentication

本文說明如何向 Ad Manager API 進行驗證。驗證方式取決於您使用的介面和程式碼執行環境，但所有 API 要求都必須包含具有 Ad Manager API 範圍的存取權杖。

Ad Manager 用戶端程式庫會使用應用程式預設憑證，產生具有 Ad Manager API 範圍的存取權杖。本指南說明如何設定應用程式預設憑證。

即使不使用用戶端程式庫，您仍須建立憑證，並使用憑證授權要求。

如要進一步瞭解驗證和授權，請參閱「使用 OAuth 2.0」指南。

判斷驗證類型

驗證類型 說明
服務帳戶 如要以專用帳戶 (而非特定人員) 的身分進行驗證，請選擇這個選項。
瞭解詳情。
網頁應用程式 如果想以任何使用者的身分進行驗證，請選擇這個選項，前提是該使用者已授權應用程式存取其 Ad Manager 資料。
瞭解詳情
本機開發 如要從本機開發環境以自己的 Google 帳戶或服務帳戶進行驗證，請選擇這個選項。

啟用 Ad Manager API

  1. 在 Google API 控制台雲端專案中啟用 Ad Manager API。

  2. 按照系統說明選取專案，或建立新專案。

建立憑證

按一下驗證類型的分頁標籤，然後按照操作說明建立憑證：

服務帳戶

在 Google Cloud 上

如要驗證在 Google Cloud 上執行的工作負載，請使用附加至程式碼執行所在運算資源的服務帳戶憑證。

舉例來說，您可以將服務帳戶附加至 Compute Engine 虛擬機器 (VM) 執行個體、Cloud Run 服務或 Dataflow 工作。對於在 Google Cloud 運算資源上執行的程式碼，我們建議採用這種驗證方式。

如要瞭解可以將服務帳戶附加至哪些資源，以及如何將服務帳戶附加至資源，請參閱附加服務帳戶的說明文件。

地端部署或其他雲端服務供應商

如要從 Google Cloud 外部設定驗證，建議使用 Workload Identity Federation。請建立憑證設定檔，並將 GOOGLE_APPLICATION_CREDENTIALS 環境變數設為指向該檔案。這種做法比建立服務帳戶金鑰更安全。

如果無法設定 Workload Identity Federation，則必須建立服務帳戶，並為服務帳戶建立金鑰：

  1. 開啟 Google API 控制台憑證頁面。

  2. 在「憑證」頁面上，依序選取「建立憑證」和「服務帳戶」。

  3. 點選要建立金鑰的服務帳戶電子郵件地址。

  4. 按一下「Keys」(金鑰) 分頁標籤。

  5. 按一下「Add key」(新增金鑰) 下拉式選單，然後選取「Create new key」(建立新的金鑰)。

  6. 選取「JSON」做為金鑰類型，然後按一下「Create」(建立)。

  7. 將環境變數 GOOGLE_APPLICATION_CREDENTIALS 設為 JSON 檔案的路徑。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

網頁應用程式

  1. 開啟 Google API 控制台憑證頁面。

  2. 如果出現提示，請選取已啟用 Ad Manager API 的專案。

  3. 在「憑證」頁面上，依序選取「建立憑證」和「OAuth 用戶端 ID」。

  4. 選取「網頁應用程式」應用程式類型。

  5. 填寫表單，然後按一下「建立」。使用 PHP、Java、Python、Ruby 和 .NET 等語言和架構的應用程式，必須指定授權的重新導向 URI。重新導向 URI 是 OAuth 2.0 伺服器可傳送回應的端點。這些端點必須遵守 Google 的驗證規則。

  6. 建立憑證後，請下載 client_secret.json 檔案。將檔案安全地儲存在只有應用程式可以存取的位置。

接著，請按照這篇文章的步驟取得 OAuth 2.0 存取權杖

本機開發

在本機環境中設定應用程式預設憑證 (ADC)。

安裝 Google Cloud CLI，然後執行下列指令進行初始化：

gcloud init

為 Google 帳戶建立本機驗證憑證，並將專案 ID 設為已啟用 Ad Manager API 的專案：

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/admanager"
gcloud auth application-default set-quota-project PROJECT_ID

或者，您也可以將環境變數 GOOGLE_APPLICATION_CREDENTIALS 設為金鑰檔案的路徑，以服務帳戶的身分進行驗證。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

設定 Ad Manager 聯播網

服務帳戶

  1. 前往 Ad Manager 聯播網。
  2. 按一下 [管理] 標籤。
  3. 確認已啟用「API 存取權」。
  4. 按一下「新增服務帳戶使用者」按鈕。
  5. 使用服務帳戶電子郵件填寫表單。服務帳戶使用者必須加入適當的角色和團隊，才能進行 API 整合。
  6. 點選「儲存」按鈕。畫面上應會顯示訊息，確認已新增服務帳戶。
  7. 如要查看現有的服務帳戶使用者，請前往「使用者」分頁，然後按一下「服務帳戶」篩選器。

網頁應用程式

  1. 前往 Ad Manager 聯播網。
  2. 按一下 [管理] 標籤。
  3. 確認已啟用「API 存取權」。

本機開發

  1. 前往 Ad Manager 聯播網。
  2. 按一下 [管理] 標籤。
  3. 確認已啟用「API 存取權」。

不使用用戶端程式庫

即使您不使用用戶端程式庫，我們仍強烈建議您使用 OAuth2 程式庫進行驗證。

如需取得存取權杖的詳細操作說明，請參閱「搭配 Google API 使用 OAuth2」。

存取權杖

在向 API 提出的要求中加入存取權杖，方法是加入 access_token 查詢參數或 Authorization HTTP 標頭 Bearer 值。建議盡可能使用 HTTP 標頭，因為查詢字串通常會顯示在伺服器記錄中。

例如：

GET /v1/networks/1234
Host: admanager.googleapis.com
Authorization: Bearer ya29.a0Ad52N3_shYLX

GET https://admanager.googleapis.com/v1/networks/1234?access_token=1/fFAGRNJru1FTz70BzhT3Zg

範圍

每個存取權杖都會與一或多個範圍建立關聯。範圍會控管存取權杖允許的資源和作業組合。Ad Manager API 有兩個範圍。如果應用程式不需要寫入資料，建議使用範圍較小的 admanager.readonly。

範圍 權限
https://www.googleapis.com/auth/admanager 查看及管理您在 Google Ad Manager 中的廣告活動。
https://www.googleapis.com/auth/admanager.readonly 在 Google Ad Manager 查看廣告活動和資料。