Method: properties.runReport

返回包含 Google Analytics 事件数据的自定义报告。报告包含根据 Google Analytics 跟踪代码收集的数据得出的统计信息。从 API 返回的数据是一个表格，其中包含所请求维度和指标的列。指标是对媒体资源中用户活动的单独衡量结果，例如活跃用户数或事件数。维度会根据一些常见条件（例如国家/地区或事件名称）细分指标。

HTTP 请求

POST https://analyticsdata.googleapis.com/v1alpha/{property=properties/*}:runReport

网址采用 gRPC 转码语法。

路径参数

参数
property

string

必需。要跟踪其事件的 Google Analytics 媒体资源标识符。在网址路径中指定，而不是在正文中指定。如需了解详情，请参阅媒体资源 ID 的查找位置。在批量请求中，此属性应未指定或与批处理级属性保持一致。

示例：properties/1234

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "dimensions": [
    {
      object (Dimension)
    }
  ],
  "metrics": [
    {
      object (Metric)
    }
  ],
  "dateRanges": [
    {
      object (DateRange)
    }
  ],
  "dimensionFilter": {
    object (FilterExpression)
  },
  "metricFilter": {
    object (FilterExpression)
  },
  "offset": string,
  "limit": string,
  "metricAggregations": [
    enum (MetricAggregation)
  ],
  "orderBys": [
    {
      object (OrderBy)
    }
  ],
  "currencyCode": string,
  "cohortSpec": {
    object (CohortSpec)
  },
  "keepEmptyRows": boolean,
  "returnPropertyQuota": boolean,
  "comparisons": [
    {
      object (Comparison)
    }
  ],
  "conversionSpec": {
    object (ConversionSpec)
  }
}
字段
dimensions[]

object (Dimension)

可选。所请求和显示的维度。
metrics[]

object (Metric)

可选。请求和显示的指标。
dateRanges[]

object (DateRange)

可选。要读取的数据的日期范围。如果请求了多个日期范围，则每个响应行都将包含一个从零开始的日期范围索引。如果两个日期范围重叠，则重叠日期的事件数据会包含在两个日期范围的响应行中。在同类群组请求中，此 dateRanges 必须处于未指定状态。
dimensionFilter

object (FilterExpression)

可选。借助维度过滤条件，您可以要求报告中仅包含特定的维度值。如需了解详情，请参阅维度过滤条件基础知识，其中包含相关示例。此过滤条件不支持使用指标。
metricFilter

object (FilterExpression)

可选。指标的过滤条件子句。在汇总报告的行之后应用，类似于 SQL 的 having 子句。此过滤条件中无法使用维度。
offset

string (int64 format)

可选。起始行的行数。第一行计为第 0 行。

分页时，第一个请求不指定偏移量；或者等效地将偏移量设置为 0；第一个请求返回前 limit 行。第二个请求将偏移量设置为第一个请求的 limit；第二个请求返回第二个 limit 行。

如需详细了解此分页参数，请参阅分页。
limit

string (int64 format)

可选。要返回的行数上限。如果未指定，则返回 10,000 行。无论您请求多少行，该 API 每次请求最多返回 25 万行。limit 必须为正值。

如果维度值的数量少于 limit，API 也可能会返回少于所请求的 limit 行。例如，维度 country 的可能值少于 300 个，因此在仅针对 country 生成报告时，即使您将 limit 设置为更高的值，也无法获得超过 300 行的数据。

如需详细了解此分页参数，请参阅分页。
metricAggregations[]

enum (MetricAggregation)

可选。指标的聚合。如果将 dimensionValues 设置为“RESERVED_(MetricAggregation)”，则汇总指标值将显示在相应行中。包含比较和多个日期范围的汇总将根据日期范围进行汇总。
orderBys[]

object (OrderBy)

可选。指定响应中各行的排序方式。如果请求同时包含比较和多个日期范围，则会针对比较应用排序。
currencyCode

string

可选。采用 ISO4217 格式的币种代码，例如“AED”“USD”“JPY”。如果该字段为空，报告将使用相应媒体资源的默认币种。
cohortSpec

object (CohortSpec)

可选。与此请求关联的同类群组。如果请求中包含同类群组，则必须包含“cohort”维度。
keepEmptyRows

boolean

可选。如果为 false 或未指定，则不会返回所有指标都等于 0 的每一行。如果值为 true，则在未被过滤器单独移除的情况下，系统会返回这些行。

无论此 keepEmptyRows 设置如何，报告中都只能显示 Google Analytics 媒体资源记录的数据。

例如，如果某个媒体资源从未记录过 purchase 事件，那么针对 eventName 维度和 eventCount 指标的查询将不会包含 eventName: "purchase" 和 eventCount: 0 的行。
returnPropertyQuota

boolean

可选。切换是否返回相应 Google Analytics 媒体资源的配额的当前状态。配额将在 PropertyQuota 中返回。
comparisons[]

object (Comparison)

可选。所请求和显示的比较配置。该请求只需要一个 comparisons 字段，即可在响应中收到比较列。
conversionSpec

object (ConversionSpec)

可选。控制转化报告。此字段是可选字段。如果设置了此字段或请求了任何转化指标，则报告将为转化报告。

响应正文

与请求对应的响应报告表。

如果成功，响应正文将包含结构如下的数据：

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

object (DimensionHeader)

描述维度列。DimensionHeaders 的数量和顺序与行中存在的维度一致。
metricHeaders[]

object (MetricHeader)

描述指标列。MetricHeaders 的数量和顺序与行中存在的指标相匹配。
rows[]

object (Row)

报告中维度值组合和指标值的行。
totals[]

object (Row)

如果请求了指标，则为指标的总计值。
maximums[]

object (Row)

如果请求，则为指标的最大值。
minimums[]

object (Row)

如果请求，则为指标的最小值。
rowCount

integer

查询结果中的总行数，无论响应中返回的行数是多少。例如，如果查询返回 175 行，并且 API 请求中包含 limit = 50，则响应将包含 rowCount = 175，但只有 50 行。

如需详细了解此分页参数，请参阅分页。
metadata

object (ResponseMetaData)

报告的元数据。
propertyQuota

object (PropertyQuota)

相应 Google Analytics 媒体资源的配额状态（包括相应请求）。
kind

string

指明相应消息所属的资源种类。此 kind 始终为固定字符串“analyticsData#runReport”。有助于区分 JSON 中的响应类型。
nextPageToken

string

可作为 pageToken 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

授权范围

需要以下 OAuth 范围之一：

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

比较

定义单个比较。大多数请求将包含多个比较对象，以便报告在比较对象之间进行比较。

JSON 表示法 
{
  "name": string,

  // Union field one_comparison can be only one of the following:
  "dimensionFilter": {
    object (FilterExpression)
  },
  "comparison": string
  // End of list of possible types for union field one_comparison.
}
字段
name

string

每次比较都会在响应中生成单独的行。在响应中，此比较对象将通过此名称进行标识。如果未指定名称，我们将使用已保存的比较的显示名称。

联合字段 one_comparison。

one_comparison 只能是下列其中一项：
dimensionFilter

object (FilterExpression)

基本比较。
comparison

string

由比较对象的资源名称标识的已保存比较对象。例如，'comparisons/1234'。

ConversionSpec

控制转化报告。

JSON 表示法 
{
  "conversionActions": [
    string
  ],
  "attributionModel": enum (AttributionModel)
}
字段
conversionActions[]

string

要纳入到报告中的转化操作 ID。如果为空，则包含所有转化。有效的转化操作 ID 可从 properties.getMetadata 方法的响应中 conversions 列表内的 conversionAction 字段检索。例如，'conversionActions/1234'。
attributionModel

enum (AttributionModel)

要在转化报告中使用的归因模型。如果未指定，则使用 DATA_DRIVEN。

AttributionModel

要在转化报告中使用的归因模型

枚举
ATTRIBUTION_MODEL_UNSPECIFIED 未指定归因模型。
DATA_DRIVEN 归因基于付费数据和自然数据驱动的模型
LAST_CLICK 归因基于“付费渠道和自然渠道 - 最终点击”模型