本指南說明應用程式如何授權傳送至 Real Time Reporting 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.readonly |
具備 Analytics (分析) API 的唯讀存取權。 |
如要透過 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 個權杖失效，依此類推。