本文件說明瞭應用程式如何取得授權，以向 Tag Manager API 發出要求。
授權要求
使用者必須先使用 Google 帳戶登入，才能在任何 Google 網站上查看帳戶資訊。同理，使用者第一次存取您的應用程式時，也必須授權應用程式存取他們的資料。
凡是您應用程式傳送至 Tag Manager API 的請求，都必須包含授權權杖。這個權杖也可讓 Google 識別您的應用程式。
關於授權通訊協定
您的應用程式必須使用 OAuth 2.0 對要求進行授權，系統不支援其他授權通訊協定。如果您的應用程式採用使用 Google 帳戶登入功能，系統會為您處理部分授權事項。
使用 OAuth 2.0 對要求進行授權
所有傳送至 Tag Manager API 的要求都必須由通過驗證的使用者進行授權。
OAuth 2.0 授權程序 (或「流程」) 的細節會根據您編寫的應用程式類型而有所不同。下列一般程序適用於所有應用程式類型：
- 建立應用程式後，請透過 Google API 控制台註冊應用程式。接著 Google 會向您提供稍後需要的資訊，例如用戶端 ID 和用戶端密碼。
- 在 Google API 控制台中啟用 Tag Manager API。(如果 API 控制台裡沒有列出該 API，則可略過這個步驟)。
- 當應用程式需要存取使用者資料時，會向 Google 要求特定的存取範圍。
- Google 會向使用者顯示同意畫面，請對方授權您的應用程式要求部分資料。
- 如果使用者同意，Google 即會授予短期存取權杖給您的應用程式。
- 您的應用程式向使用者要求資料，並且在要求中附上存取權杖。
- 如果 Google 判定您的要求與權杖有效，便會傳回您要求的資料。
部分流程包含額外步驟，例如使用「更新權杖」來取得新的存取權杖。如要進一步瞭解各類應用程式的流程，請參閱 Google 的 OAuth 2.0 說明文件。
Tag Manager API 的 OAuth 2.0 範圍資訊如下：
| 範圍 | 意義 |
|---|---|
https://www.googleapis.com/auth/tagmanager.readonly |
查看 Google 代碼管理工具容器。 |
https://www.googleapis.com/auth/tagmanager.edit.containers |
管理 Google 代碼管理工具容器。 |
https://www.googleapis.com/auth/tagmanager.delete.containers |
刪除 Google 代碼管理工具容器。 |
https://www.googleapis.com/auth/tagmanager.edit.containerversions |
管理 Google 代碼管理工具容器版本。 |
https://www.googleapis.com/auth/tagmanager.publish |
發布您的 Google 代碼管理工具容器。 |
https://www.googleapis.com/auth/tagmanager.manage.users |
管理 Google 代碼管理工具資料的使用者權限。 |
https://www.googleapis.com/auth/tagmanager.manage.accounts |
管理 Google 代碼管理工具帳戶。 |
如要透過 OAuth 2.0 要求存取權，您的應用程式需要範圍資訊，以及 Google 在您註冊應用程式時提供的資訊 (例如用戶端 ID 和用戶端密碼)。
入門課程
如要開始使用 Tag Manager API，請先使用設定工具；這項工具會逐步引導您在 Google API 控制台中建立專案、啟用 API，並建立憑證。
如要設定新的服務帳戶，請按照下列步驟操作：
- 依序按一下 [Create credentials] (建立憑證) > [Service account key] (服務帳戶金鑰)。
- 選擇將服務帳戶的公開/私密金鑰下載為標準 P12 檔案，或下載為可由 Google API 用戶端程式庫載入的 JSON 檔案。
接著，系統就會為您產生新的公開/私密金鑰，並下載至您的電腦中；這是金鑰的唯一副本，您應妥善保存這些資料。
常見的 OAuth 2.0 流程
下列指南概述特定 OAuth 2.0 流程的常見用途：
網路伺服器
這個流程適用於 Google 代碼管理工具帳戶的自動/離線/排定存取時間。
- 從伺服器自動更新代碼管理工具資訊。
用戶端
適合在使用者直接與應用程式互動，以便在瀏覽器中存取 Google 代碼管理工具帳戶時採用。這種流程不需使用伺服器端功能，但也不適合用於自動/離線/排程報表。
- 以瀏覽器為基礎的自訂設定工具。
已安裝的應用程式
適用於以套件形式發布且由使用者安裝的應用程式。應用程式或使用者必須具備瀏覽器的存取權，才能完成驗證流程。
- PC 或 Mac 上的桌面小工具。
- 適用於內容管理系統的外掛程式。與網路伺服器或用戶端相比，此流程的優點在於應用程式可使用單一 API 控制台專案。這樣可以讓使用者更輕鬆地安裝。
服務帳戶
適用於自動/離線/排定存取您自己的 Google 代碼管理工具帳戶。例如，要建立自訂工具來監控自己的 Google 代碼管理工具帳戶，並與其他使用者共用。
疑難排解
如果 access_token 已過期，或您為特定 API 呼叫使用的範圍錯誤，您會在回應中收到 401 狀態碼。
如果授權使用者沒有 Google 代碼管理工具帳戶或容器的存取權，回應中會顯示 403 狀態碼。請確認您已授權正確的使用者，並已獲得存取代碼管理工具帳戶或容器的權限。
OAuth 2.0 Playground
OAuth 2.0 Playground 可讓您透過網頁介面完成整個授權流程。這項工具也會顯示進行授權查詢時所需的所有 HTTP 要求標頭。如果您無法在自己的應用程式中取得使用授權，請嘗試透過 OAuth 2.0 Playground 執行操作。然後，您可以比較 HTTP 標頭和來自 Playground 的要求，以及應用程式傳送的內容。這項檢查可讓您輕鬆確保要求的格式正確。
授權無效
如果您在嘗試使用更新權杖時收到 invalid_grant 錯誤回應，原因可能是下列其中一項原因所造成：
- 伺服器的時鐘並未與 NTP 同步。
- 您已超過更新權杖數量上限。
應用程式可以要求多個更新權杖，以便存取單一 Google 代碼管理工具帳戶。舉例來說，如果使用者想要在多部機器上安裝應用程式，並存取同一個 Google 代碼管理工具帳戶，這項功能就能派上用場。在這種情況下，您必須有兩個更新權杖，每次安裝都要各一個。如果更新權杖的數量超出上限，舊的權杖就會失效。如果應用程式嘗試使用無效的更新權杖，系統會傳回invalid_grant錯誤回應。每個不重複的用戶端 ID/帳戶組合最多可以有 25 個更新權杖。(請注意，這項限制隨時可能變動)。 如果應用程式持續要求同一個 Client-ID/帳戶組合的更新權杖，則系統核發第 26 個權杖後，第 1 個更新權杖就會失效。第 27 個要求的更新權杖會使第 2 個核發的權杖失效，依此類推。