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)

指標匯總。匯總指標值會顯示在 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 的數量和排序與資料列中顯示的指標相符。
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)。