開發人員指南

本文說明如何使用 Real Time Reporting API 取得 Google Analytics (分析) 資料。

簡介

您可以透過 Real Time Reporting API，回報資源目前發生的活動。如要存取即時資料，您可以建立查詢並指定資料檢視 (設定檔) 和至少一個指標。 您也可以提供其他查詢參數，例如維度和篩選器來縮小查詢範圍。這項查詢會傳送至 Real Time Reporting API，並以資料表的形式傳回資料。

如果您是第一次使用 API，請參閱 Real Time Reporting API 總覽，瞭解 Real Time Reporting API 及其提供的資料。

修課條件

使用 Real Time Reporting API 取得 Google Analytics (分析) 資料前，請先完成下列事項：

  • 如需可與 API 搭配使用的程式設計語言特定用戶端程式庫的完整清單，請參閱 用戶端程式庫頁面。
  • 請參閱 參考指南，瞭解如何單獨使用 API (而不使用用戶端程式庫) 取得 Google Analytics (分析) 資料。

每個用戶端程式庫都提供單一數據分析服務物件，方便您存取所有 Real Time Reporting API 資料。如要建立服務物件，請按照下列步驟操作：

  1. 在 Google API 控制台中註冊應用程式。
  2. 授權存取 Google Analytics (分析) 資料。
  3. 建立 Analytics (分析) 服務物件。

如果您尚未完成這些步驟，請停止並參閱 Hello Google Analytics API 教學課程，其中將帶您瞭解建構 Google Analytics (分析) API 應用程式的初始步驟。知道如何使用 API 取得 Google Analytics (分析) 資料之後，

使用 Real Time Reporting API

如要使用 Real Time Reporting API，請讓應用程式：

  1. 查詢 Real Time Reporting API。
  2. 處理 API 回應。

查詢 Real Time Reporting API

數據分析服務物件提供建立 Real Time Reporting API 查詢的方法。如要進一步瞭解該 API 的查詢參數和資料，請參閱：

定義查詢後，請呼叫其 execute 方法，將查詢傳送至 Google Analytics (分析) 伺服器。

處理 API 回應

如果對 Real Time Reporting API 執行查詢成功，API 會傳回要求的資料，做為即時資料資源的一部分。如要進一步瞭解 API 回應結構和格式，請參閱 Real Time Reporting API 參考資料。

如果發生任何錯誤，API 會傳回特定狀態碼和說明該錯誤的訊息。所有應用程式都應該找出並處理錯誤。請參閱錯誤回應 一文中詳細的錯誤清單和重試建議。

程式碼示例

在「 即時資料：取得」頁面的「 範例」一節中，您可以選用各種程式設計語言的程式碼範例，以便查詢 Real Time Reporting API 及處理 API 回應。

查詢限制

以下是 Real Time API 查詢的限制：

  • 如果查詢中包含 rt:activeUsers 指標，且採用下列維度篩選器，則僅支援 AND 運算子和等式比對類型 (==)。
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    由於 rt:activeUsers 指標只會擷取網站上的活躍使用者人數，因此請勿搭配 rt:activeUsers 使用 rt:minutesAgo。也就是說，rt:activeUsers 表示 rt:minutesAgo 為 0。

  • 不支援指標篩選器。
  • 系統不支援 fields 參數。

配額管理

如「限制和配額」一文所述，Real Time Reporting API 會與其他 Google Analytics (分析) API 共用每日配額。如果您是在短時間內輪詢 Real Time Reporting API，就會很快達到每日配額限制。在這種情況下，來自其他 Google Analytics (分析) API 的要求也會停止運作，直到配額重新計算為止。

以下列舉一些可能會快速耗用配額的實作範例：

  • 您有多個即時資訊主頁，每天都會在極短的時間內查詢單一 Google Analytics (分析) 資料檢視 (設定檔) 的資料。
  • 您有一個包含大量使用者的資源，並實作了即時小工具。每次向使用者顯示小工具時，就是直接查詢 Google Analytics (分析)，而非使用快取。

如要盡可能減少配額用量並有效管理，請按照以下步驟操作：

  • 實作伺服器端快取。如有多位使用者對相同的即時資料提出要求，您應傳回快取回應，而不是直接查詢每位使用者要求的 Real Time Reporting API。接著以合理的重新整理時間間隔，定期使用最新的即時資料重新整理快取，以免超出每日配額限制。
  • 您可以指定其他維度，並在伺服器或用戶端剖析回應，藉此合併多個查詢。
  • 增加要求即時資料的時間間隔。

範例：計算重新整理的間隔

如果您預期會定期對即時資料提出要求，請根據您預期用量選取合理的重新整理時間間隔。

舉例來說，一項 Google Analytics (分析) 資料檢視 (設定檔) 的每日配額限制為每天 10,000 個要求。假設您預期在一天內對單一資料檢視 (設定檔) 進行 6,000 次查詢，則該資料檢視 (設定檔) 的剩餘要求配額為 4,000 次。

假設您決定使用 Real Time Reporting API 導入 3 個即時資訊主頁，藉此全天查詢來自同一項資料檢視 (設定檔) 的即時資料。每個資訊主頁每天可執行約 1,333 次查詢 (4,000 次查詢 / 3 個資訊主頁)。一天當中只有 86,400 秒。 因此，每個資訊主頁的重新整理時間間隔都必須超過 65 秒 (86,400 / 1,333)，這樣資料檢視 (設定檔) 的每日要求總數才會低於 4,000 的每日上限。