Core Reporting API - 授權

本指南說明應用程式如何授權給 Core Reporting API 的要求。

授權要求

使用者必須先登入自己的 Google 帳戶,才能在 Google Analytics (分析) 網站上查看帳戶資訊。同樣地,當使用者首次存取您的應用程式時,也必須授權應用程式存取他們的資料。

凡是您應用程式傳送至 Analytics (分析) API 的要求,都必須包含授權權杖,這個權杖也可讓 Google 識別您的應用程式。

關於授權通訊協定

您的應用程式必須使用 OAuth 2.0 對要求進行授權,系統不支援其他授權通訊協定。如果您的應用程式採用使用 Google 帳戶登入功能,系統會為您處理部分授權事項。

使用 OAuth 2.0 對要求進行授權

凡是對 Analytics (分析) API 發出的要求,都必須獲得經過驗證的使用者授權。

OAuth 2.0 授權程序 (或「流程」) 的細節會根據您編寫的應用程式類型而有所不同。下列一般程序適用於所有應用程式類型:

  1. 建立應用程式後,請透過 Google API 控制台註冊應用程式。接著 Google 會向您提供稍後需要的資訊,例如用戶端 ID 和用戶端密碼。
  2. 在 Google API 控制台中啟用 Analytics API。(如果 API 控制台裡沒有列出該 API,則可略過這個步驟)。
  3. 當應用程式需要存取使用者資料時,會向 Google 要求特定的存取範圍
  4. Google 會向使用者顯示同意畫面,請對方授權您的應用程式要求部分資料。
  5. 如果使用者同意,Google 即會授予短期存取權杖給您的應用程式。
  6. 您的應用程式向使用者要求資料,並且在要求中附上存取權杖。
  7. 如果 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 (分析) 資料時,就適合採用此流程。這樣就不必使用伺服器端功能,但可能會導致自動、離線或排定報表不精確。

示例:

已安裝的應用程式

此流程適用於以套件形式發布,並由使用者安裝的應用程式。如要進行這項流程,應用程式或使用者必須具備瀏覽器的存取權,才能完成驗證流程。

示例:

  • PC 或 Mac 上的桌面小工具。
  • 內容管理系統的外掛程式:相較於網路伺服器或用戶端,這個流程的優點在於應用程式可使用單一 API 控制台專案。這樣不僅能夠整合報告,也更方便使用者安裝。

服務帳戶

對於個人帳戶的 Google Analytics (分析) 資料自動存取、離線或定期存取資料,服務帳戶都很有用。舉例來說,您可以建立即時的 Google Analytics (分析) 資料資訊主頁,然後與其他使用者共用。

如要開始使用 Analytics API,請先使用設定工具;這項工具會逐步引導您在 Google API 控制台中建立專案、啟用 API,並建立憑證。

如要設定新的服務帳戶,請按照下列步驟操作:

  1. 依序按一下 [Create credentials] (建立憑證) > [Service account key] (服務帳戶金鑰)。
  2. 選擇將服務帳戶的公開/私密金鑰下載為標準 P12 檔案,或下載為可由 Google API 用戶端程式庫載入的 JSON 檔案。

接著,系統就會為您產生新的公開/私密金鑰,並下載至您的電腦中;這是金鑰的唯一副本,您應妥善保存這些資料。

疑難排解

下列情況會導致授權失敗:

  • 如果 access_token 已過期或使用的 API 範圍錯誤,您會收到 401 狀態碼。

  • 如果獲得授權的使用者沒有資料檢視 (設定檔) 的存取權,您會收到 403 狀態碼。請確認您已向正確的使用者授權,且對方確實擁有您您選取的資料檢視 (設定檔)。

OAuth 2.0 Playground

這項工具可讓您透過網頁介面完成整個授權流程。這項工具也會顯示進行授權查詢時所需的所有 HTTP 要求標頭。如果您無法在自己的應用程式中取得授權,請嘗試透過 OAuth 2.0 Playground 執行該作業。接著,您可以比較 HTTP 標頭和 Playground 中的請求,以及應用程式傳送至 Google Analytics (分析) 的要求。這項檢查可讓您輕鬆確保要求的格式正確。

授權無效

當您嘗試使用更新權杖時,以下會傳回 invalid_grant 錯誤:

應用程式可以要求多個更新權杖,以便存取單一 Google Analytics (分析) 帳戶。

舉例來說,如果使用者想要在多部電腦上安裝應用程式,並存取同一個 Google Analytics (分析) 帳戶,則每台電腦都需要不同的權杖。如果更新權杖的數量超過上限,舊的權杖就會失效。如果應用程式嘗試使用無效的更新權杖,系統會傳回 invalid_grant 錯誤回應。

每對 OAuth 2.0 用戶端和 Google Analytics (分析) 帳戶的組合最多只能有 25 個更新權杖。如果應用程式持續為同一個用戶端/帳戶配對請求更新權杖,系統發出第 26 個權杖後,先前核發的第 1 個更新權杖就會失效。第 27 個要求的更新權杖會使前 2 個先前核發的權杖失效,依此類推。