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。

示例：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)

要返回的行数。如果未指定，则返回 10000 行。无论您要求返回多少行，该 API 最多可为每个请求返回 10 万行。“limit”必须为正数。

如果维度值数量少于 limit，该 API 返回的行数也可能低于请求的 limit。例如，维度 country 的值可能少于 300 个，当仅针对 country 生成报告时，即使您将 limit 设为更高的值，也不能超过 300 行。
metricAggregations[]

enum (MetricAggregation)

指标汇总。汇总指标值将显示在将维度值设为“RESERVED_(MetricAggregation)”的行。
orderBys[]

object (OrderBy)

指定响应中各行的排序方式。
returnPropertyQuota

boolean

选择是否返回此 Google 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)

描述维度列。DimensionHeaders 的数量和 DimensionHeaders 的顺序与行中存在的维度匹配。
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），则响应会包含 rowCount（175 行），但只包含 50 行。
propertyQuota

object (PropertyQuota)

此 Google Analytics（分析）媒体资源的实时配额状态，包括此请求。
kind

string

标识此消息的资源类型。此 kind 始终是固定字符串“analyticsData#runRealtimeReport”。有助于区分 JSON 中的响应类型。

授权范围

需要以下 OAuth 范围之一：

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

分钟范围

一组连续的分钟数：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。标准 Google Analytics（分析）媒体资源最多可以请求过去 30 分钟的事件数据（startMinutesAgo <= 29），而 Google Analytics 360 媒体资源最多可以请求过去 60 分钟的事件数据（startMinutesAgo <= 59）。
endMinutesAgo

integer

查询的结束时间（以分钟为单位，包括现在）。不得早于 startMinutesAgo。例如，"endMinutesAgo": 15 指定报告应包含 15 分钟前的事件数据。

如果未指定，endMinutesAgo 默认为 0。标准 Google Analytics（分析）媒体资源可以请求过去 30 分钟的事件数据（endMinutesAgo <= 29）中的任何一分钟，而 Google Analytics 360 媒体资源可以请求过去 60 分钟的事件数据（endMinutesAgo <= 59）中的任意一分钟。