方法:reports.batchGet

返回 Google Analytics(分析)数据。

HTTP 请求

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

(此 URI 使用 URI 模板语法。)

请求正文

此请求正文包含以下结构的数据:

JSON 表示
{
  "reportRequests": [
    {
      object(ReportRequest)
    }
  ],
}
字段名称 类型 说明
reportRequests[] object(ReportRequest) 请求,每个请求都会有单独的响应。最多可有 5 个请求。所有请求都应该有相同的 dateRangesviewIdsegmentssamplingLevelcohortGroup

响应正文

如果成功的话,响应正文包含以下结构的数据:

包含来自 Reporting API batchGet 调用之报告的主响应类。

JSON 表示
{
  "reports": [
    {
      object(Report)
    }
  ],
}
字段名称 类型 说明
reports[] object(Report) 对应于每个请求的响应。

授权

需要以下 OAuth 范围之一:

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

ReportRequest

指定 Reporting API 请求的主请求类。

JSON 表示
{
  "viewId": string,
  "dateRanges": [
    {
      object(DateRange)
    }
  ],
  "samplingLevel": enum(Sampling),
  "dimensions": [
    {
      object(Dimension)
    }
  ],
  "dimensionFilterClauses": [
    {
      object(DimensionFilterClause)
    }
  ],
  "metrics": [
    {
      object(Metric)
    }
  ],
  "metricFilterClauses": [
    {
      object(MetricFilterClause)
    }
  ],
  "filtersExpression": string,
  "orderBys": [
    {
      object(OrderBy)
    }
  ],
  "segments": [
    {
      object(Segment)
    }
  ],
  "pivots": [
    {
      object(Pivot)
    }
  ],
  "cohortGroup": {
    object(CohortGroup)
  },
  "pageToken": string,
  "pageSize": number,
  "includeEmptyRows": boolean,
  "hideTotals": boolean,
  "hideValueRanges": boolean,
}
字段名称 类型 说明
viewId string 从中提取数据的 Google Analytics(分析)数据视图 IDbatchGet 方法中的每个 ReportRequest 都必须包含同一 viewId
dateRanges[] object(DateRange) 请求中的日期范围。请求最多可以有 2 个日期范围。对于请求中的每个日期范围,响应将针对维度的每个组合包含一组指标值。因此,如果有两个日期范围,将有两组指标值,一个用于原始日期范围,一个用于第二个日期范围。对于同类群组或生命周期价值请求,不应指定 reportRequest.dateRanges 字段。如果没有提供日期范围,默认的日期范围是 (startDate: 当前日期 - 7 天, endDate: 当前日期 - 1 天)。batchGet 方法中的每个 ReportRequest 都必须包含同样的 dateRanges 定义。
samplingLevel enum(Sampling) 所需的报告样本大小。如果未指定 samplingLevel 字段,将使用 DEFAULT 抽样级别。batchGet 方法中的每个 ReportRequest 都必须包含同样的 samplingLevel 定义。有关详情,请参阅开发者指南
dimensions[] object(Dimension) 请求的维度。请求总共可有 7 个维度。
dimensionFilterClauses[] object(DimensionFilterClause) 过滤维度值的维度过滤子句。它们与 AND 运算符逻辑合并。请注意,过滤操作发生在对任何维度进行汇总之前,确保返回的指标只代表相关维度的总和。
metrics[] object(Metric) 请求的指标。请求必须指定至少一个指标。请求总共可有 10 个指标。
metricFilterClauses[] object(MetricFilterClause) 指标过滤子句。它们与 AND 运算符逻辑合并。指标过滤条件只考察第一个日期范围,而不是比较日期范围。请注意,对指标的过滤操作发生在对指标进行汇总之后。
filtersExpression string 限制针对您的请求所返回数据的维度或指标过滤条件。要使用 filtersExpression,请提供要用作过滤依据的维度或指标,然后紧接着提供过滤条件表达式。例如,以下表达式选择以 Firefox 开头的 ga:browser 维度:ga:browser=~^Firefox。有关维度和指标过滤条件的详细信息,请参阅过滤条件参考
orderBys[] object(OrderBy) 输出行的排序顺序。要对两行进行比较,会按顺序应用以下元素,直到找到差异。输出中的所有日期范围会获得相同的行顺序。
segments[] object(Segment) 细分为请求返回的数据。细分定义有助于考察细分请求的一个子集。请求最多可包含四个细分。batchGet 方法中的每个 ReportRequest 都必须包含同样的 segments 定义。带细分的请求必须有 ga:segment 维度。
pivots[] object(Pivot) 数据透视定义。请求最多可以有 2 个数据透视。
cohortGroup object(CohortGroup) 与此请求相关的同类群组组。如果请求中有一个同类群组组,则必须存在 ga:cohort 维度。batchGet 方法中的每个 ReportRequest 都必须包含同样的 cohortGroup 定义。
pageToken string 获得下一页结果的延续令牌。将此令牌添至请求将返回 pageToken 后的行。pageToken 应是响应 reports.batchGet 请求而在 nextPageToken 参数中返回的值。
pageSize number 页面大小用于分页,并指定返回行的最大数目。页面大小应 >= 0。查询默认返回 1000 行。无论您要求返回多少行结果,对于每个请求,Analytics Core Reporting API 最多只能返回 10,000 行。如果维度细分数量达不到您的预期,API 返回的行数也可能小于请求的数量。例如,如果对于 ga:country 维度,可能的值不足 300,那么当只按国家/地区细分时,您能得到的结果将不会超过 300 行,即使您将 pageSize 设为超过 300 的值仍是如此。
includeEmptyRows boolean 如果设置为 false,响应不包括获取的所有指标都等于零的行。默认为 false,将排除这些行。
hideTotals boolean 如果设置为 true,则对于每一个日期范围隐藏所有匹配行的所有指标总计。默认为 false,将返回这些总计。
hideValueRanges boolean 如果设置为 true,隐藏所有匹配行的最小值和最大值。默认为 false,返回值范围。

DateRange

连续的一组日期:startDate, startDate + 1 天, ..., endDate。开始和结束日期以 ISO8601 日期格式 YYYY-MM-DD 指定。

JSON 表示
{
  "startDate": string,
  "endDate": string,
}
字段名称 类型 说明
startDate string 采用 YYYY-MM-DD 格式的查询开始日期。
endDate string 采用 YYYY-MM-DD 格式的查询结束日期。

抽样

抽样级别的值。

枚举值 说明
SAMPLING_UNSPECIFIED 如果未指定 samplingLevel 字段,将使用 DEFAULT 抽样级别。
DEFAULT 返回的响应采用默认抽样规模,速度和准确度相平衡。
SMALL 返回的响应采用较小抽样规模,但响应速度更快。
LARGE 返回的响应采用较大抽样规模,准确度更高,但是响应速度可能较慢。

维度

维度是指数据的属性。举例来说,ga:city 维度表示的是发起会话的城市,例如“巴黎”或“纽约”。

JSON 表示
{
  "name": string,
  "histogramBuckets": [
    string
  ],
}
字段名称 类型 说明
name string 要获取的维度名称,例如 ga:browser
histogramBuckets[] string
(int64 format)

如果非空,在将字符串转为 int64 后,将维度值置入范围。如果维度值不是字符串表示的整数值,将被转换为零。范围值必须采用递增顺序。每个范围在低端封闭,在高端开放。“第一个”范围包括小于第一个边界值的所有值,“最后一个”范围包括至无穷大的所有值。落入某个范围的维度值被转换为新的维度值。例如,如果给出一个列表“0, 1, 3, 4, 7”,那么我们将返回以下范围:

  • 范围 #1:值 < 0,维度值“<0”
  • 范围 #2:值落在 [0,1) 间,维度值“0”
  • 范围 #3:值落在 [1,3) 间,维度值“1-2”
  • 范围 #4:值落在 [3,4) 间,维度值“3”
  • 范围 #5:值落在 [4,7) 间,维度值“4-6”
  • 范围 #6:值 >= 7,维度值“7+”

注意:如果您要对任何维度应用直方图转变,并在排序中使用该维度,您可以使用排序类型 HISTOGRAM_BUCKET 实现这一目标。没有的话,将根据字典(词典)顺序对维度值进行排序。例如,字典顺序升序是:

"<50", "1001+", "121-1000", "50-120"

HISTOGRAM_BUCKET 顺序升序是:

"<50", "50-120", "121-1000", "1001+"

对于直方图转变维度,客户端必须明确请求 "orderType": "HISTOGRAM_BUCKET"

DimensionFilterClause

一组维度过滤条件。设置运算符值来指定过滤条件的逻辑合并方式。

JSON 表示
{
  "operator": enum(FilterLogicalOperator),
  "filters": [
    {
      object(DimensionFilter)
    }
  ],
}
字段名称 类型 说明
operator enum(FilterLogicalOperator) 合并多个维度过滤条件的运算符。如果未指定,则被视为 OR
filters[] object(DimensionFilter) 重复的过滤条件组。它们基于指定的运算符进行逻辑合并。

FilterLogicalOperator

过滤条件的逻辑合并方式。

枚举值 说明
OPERATOR_UNSPECIFIED 未指定运算符。被视为 OR
OR 逻辑 OR 运算符。
AND 逻辑 AND 运算符。

DimensionFilter

维度过滤条件指定对维度的过滤选项。

JSON 表示
{
  "dimensionName": string,
  "not": boolean,
  "operator": enum(Operator),
  "expressions": [
    string
  ],
  "caseSensitive": boolean,
}
字段名称 类型 说明
dimensionName string 作为过滤条件依据的维度。DimensionFilter 必须包含维度。
not boolean 逻辑 NOT 运算符。如果此布尔值设置为 true,则匹配的维度值将从报告中排除。默认值为 false。
operator enum(Operator) 如何将维度与表达式进行匹配。默认值是 REGEXP。
expressions[] string 要匹配的字符串或正则表达式。除非运算符是 IN_LIST,否则仅将列表的第一个值用于比较。如果运算符是 IN_LIST,则如 IN_LIST 运算符的说明所示,将使用整个列表来过滤维度。
caseSensitive boolean 匹配是否区分大小写?默认值为 false。

运算符

支持不同的匹配类型。

枚举值 说明
OPERATOR_UNSPECIFIED 如果未指定匹配类型,将被视为 REGEXP
REGEXP 匹配表达式被视为正则表达式。所有的匹配类型被视为不是正则表达式。
BEGINS_WITH 所匹配的值起始于所提供的匹配表达式。
ENDS_WITH 所匹配的值结束于所提供的匹配表达式。
PARTIAL 子字符串匹配。
EXACT 该值应该与匹配表达式完全匹配。
NUMERIC_EQUAL

整数比较过滤条件。对这些不区分大小写,且假定表达式是代表整数的字符串。失败的情况:

  • 如果表达式不是有效的 int64,客户端应该会出现错误。
  • 输入维度如果不是有效的 int64 值,不会匹配过滤条件。
NUMERIC_GREATER_THAN 检查该维度从数值上是否大于匹配表达式。阅读 NUMERIC_EQUALS 的说明,了解其限制。
NUMERIC_LESS_THAN 检查该维度从数值上是否小于匹配表达式。阅读 NUMERIC_EQUALS 的说明,了解其限制。
IN_LIST

使用该选项可以指定这样一类维度过滤条件:其表达式可从所选的一列值中提取任何值。对于对每一个响应行都采用了 OR 连接的多个完全匹配维度过滤条件,这有助于避免对其进行求值。例如:

expressions: ["A", "B", "C"]

其维度值为 A、B 或 C 的任何响应行匹配此 DimensionFilter。

指标

指标是定量测量。例如,指标 ga:users 指示所请求时间段的用户总数。

JSON 表示
{
  "expression": string,
  "alias": string,
  "formattingType": enum(MetricType),
}
字段名称 类型 说明
expression string 请求中的指标表达式。表达式构建自一个或多个指标和数字。接受的运算符包括:加号 (+)、减号 (-)、否定(一元 -)、除号 (/)、乘号 (*)、英文括号、正基数数字 (0-9),可以包含小数,且仅限于 1024 个字符。ga:totalRefunds/ga:users 就是一个例子,在大多数情况下,指标表达式只是一个单一指标名称,如 ga:users。添加混合的 MetricType(如 CURRENCY + PERCENTAGE)指标会导致出现意外结果。
alias string 指标表达式的别名是表达式的替代名称。别名可用于过滤和排序。此字段是可选的,如果表达式不是单个指标,而是一个复杂的表达式,无法用在过滤和排序中,此字段就是有用的。别名也用在响应列标题中。
formattingType enum(MetricType) 指定指标表达式的格式设置方式,例如 INTEGER

MetricType

指标的类型。

枚举值 说明
METRIC_TYPE_UNSPECIFIED 指标类型未指定。
INTEGER 整数指标。
FLOAT 浮点数指标。
CURRENCY 币种指标。
PERCENT 百分数指标。
TIME 采用 HH:MM:SS 格式的时间指标。

MetricFilterClause

代表一组指标过滤条件。设置运算符值来指定过滤条件的逻辑合并方式。

JSON 表示
{
  "operator": enum(FilterLogicalOperator),
  "filters": [
    {
      object(MetricFilter)
    }
  ],
}
字段名称 类型 说明
operator enum(FilterLogicalOperator) 合并多个指标过滤条件的运算符。如果未指定,则被视为 OR
filters[] object(MetricFilter) 重复的过滤条件组。它们基于指定的运算符进行逻辑合并。

MetricFilter

MetricFilter 指定对指标的过滤条件。

JSON 表示
{
  "metricName": string,
  "not": boolean,
  "operator": enum(Operator),
  "comparisonValue": string,
}
字段名称 类型 说明
metricName string 将作为过滤依据的指标。metricFilter 必须包含指标名。指标名既可以是前面定义为指标的别名,也可以是指标表达式。
not boolean 逻辑 NOT 运算符。如果此布尔值设置为 true,则匹配的指标值将从报告中排除。默认值为 false。
operator enum(Operator) 指标是 EQUALLESS_THAN 还是 GREATER_THAN comparisonValue,默认是 EQUAL。如果运算符是 IS_MISSING,则检查指标是否缺失以及忽略 comparisonValue。
comparisonValue string 要比较的值。

运算符

不同的比较类型选项。

枚举值 说明
OPERATOR_UNSPECIFIED 如果未指定运算符,将被视为 EQUAL
EQUAL 指标值是否应恰好等于比较值。
LESS_THAN 指标值是否应小于比较值。
GREATER_THAN 指标值是否应大于比较值。
IS_MISSING 验证指标是否缺失。不考虑 comparisonValue。

OrderBy

指定排序选项。

JSON 表示
{
  "fieldName": string,
  "orderType": enum(OrderType),
  "sortOrder": enum(SortOrder),
}
字段名称 类型 说明
fieldName string 要排序的字段。默认的排序顺序是升序。例如:ga:browser。请注意,此处您只能指定一个字段用于排序。例如,ga:browser, ga:city 无效。
orderType enum(OrderType) 排序类型。默认的 orderType 是 VALUE
SortOrder enum(SortOrder) 字段的排序顺序。

OrderType

OrderType 控制排序顺序的确定方式。

枚举值 说明
ORDER_TYPE_UNSPECIFIED 未指定的顺序类型将视为根据值进行排序。
VALUE 排序顺序依据所选列的值;仅考察第一个日期范围。
DELTA 排序顺序依据前两个日期范围之间所选列的值差。仅当恰好有两个日期范围时可用。
SMART 排序顺序依据所选列的加权值。如果列的格式是 n/d,那么该比率的加权值将是 (n + totals.n)/(d + totals.d)。只对表示比率的指标可用。
HISTOGRAM_BUCKET 直方图顺序类型仅适用于直方图范围非空的维度列。
DIMENSION_AS_INTEGER 如果维度是固定长度的数字,普通排序完全能正常操作。如果维度是可变长度的数字,可以使用 DIMENSION_AS_INTEGER

SortOrder

此排序的排序顺序。

枚举值 说明
SORT_ORDER_UNSPECIFIED 如果未指定排序顺序,默认是升序。
ASCENDING 升序排序。该字段采用升序方式进行排序。
DESCENDING 降序排序。该字段采用降序方式进行排序。

细分

是否需要对该报告进行细分的细分定义。细分是指 Google Analytics(分析)数据的一个子集。例如,在整个用户群中,可使用一个细分指定来自特定国家/地区或城市的用户。

JSON 表示
{

  // Union field dynamicOrById can be only one of the following:
  "dynamicSegment": {
    object(DynamicSegment)
  },
  "segmentId": string,
  // End of list of possible types for union field dynamicOrById.
}
字段名称 类型 说明
联合字段 dynamicOrById。对细分可以使用 DynamicSegment 进行动态定义或使用内置或自定义细分的 ID 定义。dynamicOrById 只能是下列值之一:
dynamicSegment object(DynamicSegment) 请求中的动态细分定义。
segmentId string 内置或自定义细分的细分 ID,如 gaid::-3

DynamicSegment

请求中定义细分的动态细分定义。一个细分可以选择用户、会话或选择这两者。

JSON 表示
{
  "name": string,
  "userSegment": {
    object(SegmentDefinition)
  },
  "sessionSegment": {
    object(SegmentDefinition)
  },
}
字段名称 类型 说明
name string 动态细分的名称。
userSegment object(SegmentDefinition) 选择包含在细分中的用户的用户细分。
sessionSegment object(SegmentDefinition) 选择包含在细分中的会话的会话细分。

SegmentDefinition

SegmentDefinition 将细分定义为一组使用逻辑 AND 操作合并起来的 SegmentFilters。

JSON 表示
{
  "segmentFilters": [
    {
      object(SegmentFilter)
    }
  ],
}
字段名称 类型 说明
segmentFilters[] object(SegmentFilter) 将细分定义为一组使用逻辑 AND 操作合并起来的细分过滤条件。

SegmentFilter

SegmentFilter 将细分定义为简单细分或顺序细分。简单细分条件包含选择会话或用户的维度和指标条件。顺序细分条件可用于基于顺序条件选择用户或会话。

JSON 表示
{
  "not": boolean,

  // Union field simpleOrSequence can be only one of the following:
  "simpleSegment": {
    object(SimpleSegment)
  },
  "sequenceSegment": {
    object(SequenceSegment)
  },
  // End of list of possible types for union field simpleOrSequence.
}
字段名称 类型 说明
not boolean

如果为 true,匹配简单细分或顺序细分的补集。例如,为了匹配不是来自“New York”的所有访问,我们可以如下定义细分:

  "sessionSegment": {
    "segmentFilters": [{
      "simpleSegment" :{
        "orFiltersForSegment": [{
          "segmentFilterClauses":[{
            "dimensionFilter": {
              "dimensionName": "ga:city",
              "expressions": ["New York"]
            }
          }]
        }]
      },
      "not": "True"
    }]
  },
联合字段 simpleOrSequence。是简单细分还是顺序细分定义。simpleOrSequence 只能是以下值之一:
simpleSegment object(SimpleSegment) 简单细分条件由可以合并的一个或多个维度/指标条件组成
sequenceSegment object(SequenceSegment) 顺序条件由一个或多个步骤组成,其中每个步骤都由一个或多个维度/指标条件定义。利用特殊的顺序运算符可以将多个步骤合并在一起。

SimpleSegment

简单细分条件由可以合并的一个或多个维度/指标条件组成。

JSON 表示
{
  "orFiltersForSegment": [
    {
      object(OrFiltersForSegment)
    }
  ],
}
字段名称 类型 说明
orFiltersForSegment[] object(OrFiltersForSegment) 一列使用逻辑 AND 运算符合并的细分过滤条件组。

OrFiltersForSegment

OR 组中的一列细分过滤条件使用逻辑 OR 运算符合并。

JSON 表示
{
  "segmentFilterClauses": [
    {
      object(SegmentFilterClause)
    }
  ],
}
字段名称 类型 说明
segmentFilterClauses[] object(SegmentFilterClause) 使用 OR 运算符合并的细分过滤条件列表。

SegmentFilterClause

细分定义中所用的过滤条件子句,可以采用指标或维度过滤条件。

JSON 表示
{
  "not": boolean,

  // Union field dimensionOrMetricFilter can be only one of the following:
  "dimensionFilter": {
    object(SegmentDimensionFilter)
  },
  "metricFilter": {
    object(SegmentMetricFilter)
  },
  // End of list of possible types for union field dimensionOrMetricFilter.
}
字段名称 类型 说明
not boolean 匹配过滤条件的补集 (!)。
联合字段 dimensionOrMetricFilter。维度或指标过滤条件。dimensionOrMetricFilter 只能是以下值之一:
dimensionFilter object(SegmentDimensionFilter) 细分定义的维度过滤条件。
metricFilter object(SegmentMetricFilter) 细分定义的指标过滤条件。

SegmentDimensionFilter

维度过滤条件指定对维度的过滤选项。

JSON 表示
{
  "dimensionName": string,
  "operator": enum(Operator),
  "caseSensitive": boolean,
  "expressions": [
    string
  ],
  "minComparisonValue": string,
  "maxComparisonValue": string,
}
字段名称 类型 说明
dimensionName string 应用过滤条件的维度名称。
operator enum(Operator) 将维度与表达式进行匹配所用的运算符。
caseSensitive boolean 匹配是否应区分大小写,对于 IN_LIST 运算符忽略。
expressions[] string 表达式列表,只有第一个元素用于所有运算符
minComparisonValue string BETWEEN 匹配类型的最小比较值。
maxComparisonValue string BETWEEN 匹配类型的最大比较值。

运算符

支持不同的匹配类型。

枚举值 说明
OPERATOR_UNSPECIFIED 如果未指定匹配类型,将被视为 REGEXP。
REGEXP 匹配表达式被视为正则表达式。所有其他匹配类型都不会被视为正则表达式。
BEGINS_WITH 所匹配的值起始于所提供的匹配表达式。
ENDS_WITH 所匹配的值结束于所提供的匹配表达式。
PARTIAL 子字符串匹配。
EXACT 该值应该与匹配表达式完全匹配。
IN_LIST

使用该选项可以指定这样一类维度过滤条件:其表达式可从所选的一列值中提取任何值。对于对每一个响应行都采用了 OR 连接的多个完全匹配维度过滤条件,这有助于避免对其进行求值。例如:

expressions: ["A", "B", "C"]

其维度值为 A、B 或 C 的任何响应行匹配此 DimensionFilter。

NUMERIC_LESS_THAN

整数比较过滤条件。对这些不区分大小写,且假定表达式是代表整数的字符串。失败的情况:

  • 如果表达式不是有效的 int64,客户端应该会出现错误。
  • 输入维度如果不是有效的 int64 值,不会匹配过滤条件。

检查该维度从数值上是否小于匹配表达式。

NUMERIC_GREATER_THAN 检查该维度从数值上是否大于匹配表达式。
NUMERIC_BETWEEN 检查该维度从数值上是否落在匹配表达式的最小值和最大值之间,不含边界值。

SegmentMetricFilter

细分过滤条件子句中所用的指标过滤条件。

JSON 表示
{
  "scope": enum(Scope),
  "metricName": string,
  "operator": enum(Operator),
  "comparisonValue": string,
  "maxComparisonValue": string,
}
字段名称 类型 说明
scope enum(Scope) 指标范围可以界定定义指标的级别。指定的指标范围必须等于或大于其主要范围(根据数据模型中的定义)。主要范围的定义依据的是该细分是否选择用户或会话。
metricName string 将作为过滤依据的指标。metricFilter 必须包含指标名。
operator enum(Operator) 指定对指标进行比较所执行的操作。默认是 EQUAL
comparisonValue string 要比较的值。如果运算符是 BETWEEN,此值被视为最小比较值。
maxComparisonValue string 只对 BETWEEN 运算符使用最大比较值。

范围

指标范围可以界定指标定义的级别:PRODUCTHITSESSIONUSER。指标值的报告范围也可以大于其主要范围。例如,对于 ga:pageviewsga:transactions,只需将发生在这些会话中的每个匹配或用户实施的每个匹配予以累加,报告它们时就能使用 SESSION 级别和 USER 级别。

枚举值 说明
UNSPECIFIED_SCOPE 如果未指定范围,则取决于细分是要选择用户还是会话,将默认为条件范围 USERSESSION
PRODUCT 产品范围。
HIT 匹配范围。
SESSION 会话范围。
USER 用户范围。

运算符

不同的比较类型选项。

枚举值 说明
UNSPECIFIED_OPERATOR 未指定的运算符将被视为 LESS_THAN 运算符。
LESS_THAN 检查该指标值是否小于比较值。
GREATER_THAN 检查该指标值是否大于比较值。
EQUAL 等于运算符。
BETWEEN 对于“之间”运算符,最小值和最大值都是被排除的。我们使用 LTGT 进行比较。

SequenceSegment

顺序条件由一个或多个步骤组成,其中每个步骤都由一个或多个维度/指标条件定义。利用特殊的顺序运算符可以将多个步骤合并在一起。

JSON 表示
{
  "segmentSequenceSteps": [
    {
      object(SegmentSequenceStep)
    }
  ],
  "firstStepShouldMatchFirstHit": boolean,
}
字段名称 类型 说明
segmentSequenceSteps[] object(SegmentSequenceStep) 顺序中的步骤列表。
firstStepShouldMatchFirstHit boolean 如果设置,第一步条件必须与(日期范围内)访问者的第一个匹配相匹配。

SegmentSequenceStep

细分顺序定义。

JSON 表示
{
  "orFiltersForSegment": [
    {
      object(OrFiltersForSegment)
    }
  ],
  "matchType": enum(MatchType),
}
字段名称 类型 说明
orFiltersForSegment[] object(OrFiltersForSegment) 顺序被指定为使用 AND 运算符合并的一列 Or 组合的过滤条件。
matchType enum(MatchType) 指定下一步骤是紧随此步骤,还是可以发生在此步骤之后的任意时间。

MatchType

此顺序的匹配类型。

枚举值 说明
UNSPECIFIED_MATCH_TYPE 未指定匹配类型被视为“precedes”(先于)。
PRECEDES 运算符表示,前一个步骤先于后一个步骤发生。
IMMEDIATELY_PRECEDES 运算符表示,后一个步骤紧接着前一个步骤发生。

数据透视

“数据透视”描述了请求中的数据透视部分。通过在第二维度上对数据进行透视,数据透视有助于为某些报告重新排列表格中的信息。

JSON 表示
{
  "dimensions": [
    {
      object(Dimension)
    }
  ],
  "dimensionFilterClauses": [
    {
      object(DimensionFilterClause)
    }
  ],
  "metrics": [
    {
      object(Metric)
    }
  ],
  "startGroup": number,
  "maxGroupCount": number,
}
字段名称 类型 说明
dimensions[] object(Dimension) 显示为数据透视列的维度列表。数据透视最多可以有 4 个维度。数据透视维度属于对请求中所允许维度总数的限制。
dimensionFilterClauses[] object(DimensionFilterClause) DimensionFilterClauses 以 AND 运算符进行逻辑合并:只有所有这些 DimensionFilterClauses 都包含的数据才会对此数据透视区域中的值做出贡献。维度过滤条件可用于限制数据透视区域中所显示的列。例如,如果您以 ga:browser 作为数据透视区域中的请求维度,并且指定关键过滤条件,将 ga:browser 限制为“IE”或“Firefox”,那么只有这两个浏览器会显示为列。
metrics[] object(Metric) 数据透视指标。请求中允许的指标总数限制就包含数据透视指标。
startGroup number

如果请求 k 个指标,则响应将在报告中包含 k 列的某个与数据相关的倍数。例如,如果您对维度 ga:browser 进行数据透视,则对于“Firefox”,您会得到 k 列,对于“IE”得到 k 列,对于“Chrome”得到 k 列,等等。这些列组的排序取决于 k 个值中第一个的“总计”值的降序。如果值不相上下,则先依据第一个数据透视维度的词典排序结果,再依据第二个数据透视维度的词典排序结果,以此类推。例如,如果 Firefox、IE 和 Chrome 的第一个值的总计分别为 8、2、8,则列的顺序将是 Chrome、Firefox、IE。

以下内容供您选择在响应中加入 k 列的哪些组合。

maxGroupCount number 指定返回的最大组数。默认值是 10,最大值也是 1000。

CohortGroup

定义同类群组的组。例如:

"cohortGroup": {
  "cohorts": [{
    "name": "cohort 1",
    "type": "FIRST_VISIT_DATE",
    "dateRange": { "startDate": "2015-08-01", "endDate": "2015-08-01" }
  },{
    "name": "cohort 2"
     "type": "FIRST_VISIT_DATE"
     "dateRange": { "startDate": "2015-07-01", "endDate": "2015-07-01" }
  }]
}
JSON 表示
{
  "cohorts": [
    {
      object(Cohort)
    }
  ],
  "lifetimeValue": boolean,
}
字段名称 类型 说明
cohorts[] object(Cohort) 同类群组的定义。
lifetimeValue boolean

启用生命周期价值 (LTV)。LTV 衡量通过不同渠道获得的用户的生命周期价值。如果 lifetimeValue 的值是 false,请参阅同类群组分析生命周期价值

  • 这些指标值接近于网络界面同类群组报告中的值。
  • 同类群组定义日期范围必须与日历周和月一致,即当请求 ga:cohortNthWeek 时,同类群组定义中的 startDate 应该是星期日,而 endDate 应该是后面的星期六;而对于 ga:cohortNthMonthstartDate 应该是该月的第一天,而 endDate 应该是该月的最后一天。

如果 lifetimeValue 为 true:

  • 这些指标值对应于网络界面生命周期价值报告中的值。
  • 生命周期价值报告会向您显示在赢得用户之后的 90 天内,用户价值(收入)和互动(应用浏览次数、目标达成次数、会话次数和会话时长)的增长情况。
  • 这些指标计算为每位用户在每个时间增量的累积平均值。
  • 同类群组定义日期范围不需要与日历周和月的边界一致。
  • viewId 必须是 app view ID

同类群组

定义同类群组。同类群组是具有共同特征的一组用户。例如,流量获取日期相同的所有用户属于同一个同类群组。

JSON 表示
{
  "name": string,
  "type": enum(Type),
  "dateRange": {
    object(DateRange)
  },
}
字段名称 类型 说明
name string 同类群组的唯一的名称。如果没有定义,名称将以值 cohort_[1234...] 自动生成。
type enum(Type) 同类群组的类型。到目前为止唯一支持的类型是 FIRST_VISIT_DATE。如果此字段未指定,同类群组被视为 FIRST_VISIT_DATE 类型的同类群组。
dateRange object(DateRange) 用于 FIRST_VISIT_DATE 同类群组,该同类群组选择首次访问日期落在 DateRange 中定义的开始日期和结束日期之间的用户。日期范围应该与同类群组请求一致。如果请求包含 ga:cohortNthDay,应该恰好一天;如果是 ga:cohortNthWeek,应该与周的边界一致(开始于星期日,结束于星期六);对于 ga:cohortNthMonth,日期范围应该与月一致(开始于该月的第一天,结束于该月的最后一天)。对于 LTV 请求,没有这样的限制。对于 reportsRequest.dateRanges 字段,不需要提供日期范围。

类型

同类群组的类型。

枚举值 说明
UNSPECIFIED_COHORT_TYPE 如果未指定,则被视为 FIRST_VISIT_DATE
FIRST_VISIT_DATE 根据首次访问日期选择的同类群组。

报告

对应于请求的数据响应。

JSON 表示
{
  "columnHeader": {
    object(ColumnHeader)
  },
  "data": {
    object(ReportData)
  },
  "nextPageToken": string,
}
字段名称 类型 说明
columnHeader object(ColumnHeader) 列标题。
data object(ReportData) 响应数据。
nextPageToken string 获取列表中下一页结果的网页令牌。

ColumnHeader

列标题。

JSON 表示
{
  "dimensions": [
    string
  ],
  "metricHeader": {
    object(MetricHeader)
  },
}
字段名称 类型 说明
dimensions[] string 响应中的维度名称。
metricHeader object(MetricHeader) 响应中指标的指标标头。

MetricHeader

指标的标头。

JSON 表示
{
  "metricHeaderEntries": [
    {
      object(MetricHeaderEntry)
    }
  ],
  "pivotHeaders": [
    {
      object(PivotHeader)
    }
  ],
}
字段名称 类型 说明
metricHeaderEntries[] object(MetricHeaderEntry) 响应中指标的标头。
pivotHeaders[] object(PivotHeader) 响应中数据透视的标头。

MetricHeaderEntry

指标的标头。

JSON 表示
{
  "name": string,
  "type": enum(MetricType),
}
字段名称 类型 说明
name string 标头的名称。
类型 enum(MetricType) 指标的类型,例如 INTEGER

PivotHeader

请求中定义的每个数据透视部分的标头。

JSON 表示
{
  "pivotHeaderEntries": [
    {
      object(PivotHeaderEntry)
    }
  ],
  "totalPivotGroupsCount": number,
}
字段名称 类型 说明
pivotHeaderEntries[] object(PivotHeaderEntry) 单个数据透视部分的标头。
totalPivotGroupsCount number 此数据透视的总组数。

PivotHeaderEntry

与响应的数据透视部分所请求的指标相对应的每个指标列的标题。

JSON 表示
{
  "dimensionNames": [
    string
  ],
  "dimensionValues": [
    string
  ],
  "metric": {
    object(MetricHeaderEntry)
  },
}
字段名称 类型 说明
dimensionNames[] string 数据透视响应中的维度名称。
dimensionValues[] string 数据透视中维度的值。
metric object(MetricHeaderEntry) 数据透视中指标的指标标头。

ReportData

报告的数据部分。

JSON 表示
{
  "rows": [
    {
      object(ReportRow)
    }
  ],
  "totals": [
    {
      object(DateRangeValues)
    }
  ],
  "rowCount": number,
  "minimums": [
    {
      object(DateRangeValues)
    }
  ],
  "maximums": [
    {
      object(DateRangeValues)
    }
  ],
  "samplesReadCounts": [
    string
  ],
  "samplingSpaceSizes": [
    string
  ],
  "isDataGolden": boolean,
}
字段名称 类型 说明
rows[] object(ReportRow) 维度的每一个唯一组合都有一个 ReportRow。
totals[] object(DateRangeValues) 对于每一个请求的日期范围,对于与查询匹配的所有行组,每一个请求的值格式将得到一个总计。值格式总计的计算方式是,首先加总值格式中提到的指标,然后将值格式作为标量表达式求值。例如,对于 3 / (ga:sessions + 2) 的“总计”,我们计算 3 / ((sum of all relevant ga:sessions) + 2)。在分页之前计算总计。
rowCount number 此查询匹配行的总数。
minimums[] object(DateRangeValues) 所有匹配行的最小值和最大值。如果请求中的 hideValueRanges 为 false 或者 rowCount 是零,这些均为空。
maximums[] object(DateRangeValues) 所有匹配行的最小值和最大值。如果请求中的 hideValueRanges 为 false 或者 rowCount 是零,这些均为空。
samplesReadCounts[] string
(int64 format)
如果对结果进行抽样,将返回所读取样本的总数,每个日期范围一个条目。如果未对结果进行抽样,则不会定义此字段。有关详情,请参阅开发者指南
samplingSpaceSizes[] string
(int64 format)
如果对结果进行抽样,将返回所提供样本的总数,每个日期范围一个条目。如果未对结果进行抽样,则不会定义此字段。有关详情,请参阅开发者指南
isDataGolden boolean 表示对这一请求的响应是否是黄金响应。如果在以后的某个时间点发出完全相同的请求而不会产生任何新的结果,即可说数据是黄金数据。

ReportRow

报告中的一行。

JSON 表示
{
  "dimensions": [
    string
  ],
  "metrics": [
    {
      object(DateRangeValues)
    }
  ],
}
字段名称 类型 说明
dimensions[] string 所请求维度的列表。
metrics[] object(DateRangeValues) 每个请求的 DateRange 的指标列表。

DateRangeValues

用于针对单个 DateRange/维度组合返回一列指标

JSON 表示
{
  "values": [
    string
  ],
  "pivotValueRegions": [
    {
      object(PivotValueRegion)
    }
  ],
}
字段名称 类型 说明
values[] string 每个值对应于请求中的每个指标。
pivotValueRegions[] object(PivotValueRegion) 每个数据透视区域的值。

PivotValueRegion

数据透视区域中的指标值。

JSON 表示
{
  "values": [
    string
  ],
}
字段名称 类型 说明
values[] string 每个数据透视区域中的指标值。

试试看!