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