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,API 最多只能傳回 250,000 列資料。limit 必須為正數。

如果維度值少於 limit,API 傳回的列數也可以少於要求的 limit。舉例來說,維度「country」的可能值少於 300 個,因此如果只針對「country」製作報表,即使您將 limit 設為較高的值,也無法取得超過 300 列。

metricAggregations[]

enum (MetricAggregation)

指標匯總。系統會將匯總指標值顯示在 dimensionValues 設為「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)

說明維度欄。DimensionsHeaders 的數量和排序方式與資料列中顯示的維度相符。

metricHeaders[]

object (MetricHeader)

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

rows[]

object (Row)

報表中的維度值組合和指標值列。

totals[]

object (Row)

依據要求,指標的總值。

maximums[]

object (Row)

依據要求,指標的最大值。

minimums[]

object (Row)

依要求提供指標的最小值。

rowCount

integer

查詢結果中的資料列總數。rowCount 與回應中傳回的列數和 limit 要求參數無關。舉例來說,如果查詢傳回 175 列,並在 API 要求中包含 limit 的 50,則回應將包含 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

連續分鐘數:startMinutesAgostartMinutesAgo + 1、...、endMinutesAgo。要求長度上限為 2 分鐘。

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

string

為這個分鐘範圍指定名稱。在報表回應中,維度「dateRange」會列為這個名稱。如果有設定,開頭不得為 date_range_RESERVED_。如未設定,分鐘範圍會在要求中以零的索引命名:date_range_0date_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) 中要求一分鐘的時間。