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。

示例：property/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 最多只能返回 25 万行。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)

描述维度列。DimensionHeader 的数量和 DimensionHeader 的顺序与行中显示的维度一致。
metricHeaders[]

object (MetricHeader)

描述指标列。MetricHeader 的数量和 MetricHeader 的顺序与行中显示的指标一致。
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)

此 Google 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)。