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 控制台 Cloud 專案中啟用 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 聯盟，則必須建立服務帳戶，並為該服務帳戶建立金鑰：

  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. 選取「Web application」(網頁應用程式) 應用程式類型。

  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 程式庫進行驗證。

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

存取權杖

在 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 查看廣告活動和資料。