Method: properties.runRealtimeReport

傳回資源的即時事件資料自訂報表。事件傳送到 Google Analytics (分析) 後幾秒內，即時報表就會列出。即時報表會顯示過去到 30 分鐘 (Google Analytics (分析) 360 資源最長 60 分鐘) 的事件和使用資料。

如要瞭解如何建立即時要求及解讀回應，請參閱「建立即時報表」一文。

HTTP 要求

POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runRealtimeReport

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
property

string

Google Analytics (分析) GA4 資源 ID，其中包含追蹤事件的相關資料。已在網址路徑指定，而非主體。詳情請參閱「查看資源 ID 的方式」一文。

範例：properties/1234

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "dimensions": [
    {
      object (Dimension)
    }
  ],
  "metrics": [
    {
      object (Metric)
    }
  ],
  "dimensionFilter": {
    object (FilterExpression)
  },
  "metricFilter": {
    object (FilterExpression)
  },
  "limit": string,
  "metricAggregations": [
    enum (MetricAggregation)
  ],
  "orderBys": [
    {
      object (OrderBy)
    }
  ],
  "returnPropertyQuota": boolean,
  "minuteRanges": [
    {
      object (MinuteRange)
    }
  ]
}
欄位
dimensions[]

object (Dimension)

要求及顯示的維度。
metrics[]

object (Metric)

要求及顯示的指標，
dimensionFilter

object (FilterExpression)

維度的篩選器子句。這個篩選器無法使用指標。
metricFilter

object (FilterExpression)

指標的篩選器子句。套用於匯總後階段，與 SQL 有子句類似。無法在這個篩選器中使用維度。
limit

string (int64 format)

要傳回的列數。如果未指定，則會傳回 10,000 列。無論您要求的數量為何，API 每個要求最多只能傳回 250,000 個資料列。limit 必須為正數。

如果維度值數量不是 limit，API 傳回的資料列也會少於所要求的 limit 列數。舉例來說，「country」維度的可能值少於 300 個，因此在只針對 country 製作報表時，即使您將 limit 設為較高的值，資料最多只能顯示 300 列。
metricAggregations[]

enum (MetricAggregation)

指標匯總。匯總指標值會顯示在 DimensionsValue 設為「RESERVED_(MetricAggregation)」的資料列中。
orderBys[]

object (OrderBy)

指定資料列在回應中的排序方式。
returnPropertyQuota

boolean

切換是否要傳回這個 Analytics (分析) 資源的即時配額的目前狀態。系統會在 PropertyQuota 中傳回配額。
minuteRanges[]

object (MinuteRange)

要讀取的事件資料分鐘範圍。如未指定，系統會使用過去 30 分鐘的一分鐘範圍。如果要求多個分鐘範圍，則每個回應列將包含以零為基準的範圍索引。如果兩分鐘範圍重疊，這兩個分鐘範圍的回應列中會含有重疊分鐘數的事件資料。

回應主體

與要求對應的回應即時報表表格。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "dimensionHeaders": [
    {
      object (DimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (MetricHeader)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totals": [
    {
      object (Row)
    }
  ],
  "maximums": [
    {
      object (Row)
    }
  ],
  "minimums": [
    {
      object (Row)
    }
  ],
  "rowCount": integer,
  "propertyQuota": {
    object (PropertyQuota)
  },
  "kind": string
}
欄位
dimensionHeaders[]

object (DimensionHeader)

說明維度欄。DimensionsHeader 數量和 DimensionsHeader 數量的按順序與列數相符。
metricHeaders[]

object (MetricHeader)

說明指標欄。MetricHeaders 的數量和 MetricHeaders 的數量與資料列中顯示的指標相符。
rows[]

object (Row)

報表中維度值組合和指標值的資料列。
totals[]

object (Row)

依要求，指標的總計值。
maximums[]

object (Row)

如果收到要求，指標值的最大值。
minimums[]

object (Row)

按要求表示指標的最小值。
rowCount

integer

查詢結果中的資料列總數。rowCount 與回應中傳回的資料列數量和 limit 要求參數無關。舉例來說，如果查詢傳回 175 列，並在 API 要求中包含 50 的 limit，則回應中會包含 175 的 rowCount，但只有 50 列。
propertyQuota

object (PropertyQuota)

這項 Analytics (分析) 資源的即時配額狀態，包括這項要求。
kind

string

識別此訊息的資源種類。這個 kind 一律是固定字串「analyticsData#runRealtimeReport」。適合區分 JSON 中的回應類型。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

MinuteRange

連續分鐘數：startMinutesAgo、startMinutesAgo + 1、...、endMinutesAgo。最多可以要求 2 分鐘的範圍。

JSON 表示法 
{
  "name": string,
  "startMinutesAgo": integer,
  "endMinutesAgo": integer
}
欄位
name

string

指派這個分鐘範圍的名稱。報表回應中的維度 dateRange 為這個名稱。設定後不得以 date_range_ 或 RESERVED_ 開頭。如未設定，分鐘範圍會在要求中的以零為基礎的索引命名：date_range_0、date_range_1 等。
startMinutesAgo

integer

包含查詢的開始分鐘數，以分鐘為單位。舉例來說，"startMinutesAgo": 29 指定報表應包含 29 分鐘前和之後的事件資料。不得晚於 endMinutesAgo。

如果未指定，startMinutesAgo 預設為 29。標準 Analytics (分析) 資源最多可要求過去 30 分鐘的事件資料 (startMinutesAgo <= 29)，360 Analytics (分析) 資源最多可要求最近 60 分鐘的事件資料 (startMinutesAgo <= 59)。
endMinutesAgo

integer

查詢的結束分鐘數，以分鐘為單位。不得早於 startMinutesAgo。舉例來說，"endMinutesAgo": 15 指定報表應包含 15 分鐘前的事件資料。

如果未指定，endMinutesAgo 的預設值為 0。標準 Analytics (分析) 資源可要求過去 30 分鐘內的事件資料 (endMinutesAgo <= 29)，且 360 Analytics (分析) 資源可要求過去 60 分鐘的事件資料 (endMinutesAgo <= 59) 中任何一分鐘。