User Deletion API - 授權

本指南說明應用程式如何授權對 User Deletion 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.user.deletion 使用 User Deletion 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 個權杖失效,以此類推。