REST Resource: properties.reportTasks

资源：ReportTask

特定报告任务配置。

JSON 表示法 
{
  "name": string,
  "reportDefinition": {
    object (ReportDefinition)
  },
  "reportMetadata": {
    object (ReportMetadata)
  }
}
字段
name

string

仅限输出。标识符。创建时分配的报告任务资源名称。格式：“properties/{property}/reportTasks/{reportTask}”
reportDefinition

object (ReportDefinition)

可选。用于提取报告数据的报告定义，描述了报告的结构。它通常包含报告中将包含的字段以及用于过滤数据的条件。
reportMetadata

object (ReportMetadata)

仅限输出。特定报告任务的报告元数据，其中包含有关报告的信息。它通常包含以下信息：报告的资源名称、报告的状态、报告的创建时间戳等。

ReportDefinition

有关如何运行报告的定义。

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,
  "samplingLevel": enum (SamplingLevel)
}
字段
dimensions[]

object (Dimension)

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

object (Metric)

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

object (DateRange)

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

object (FilterExpression)

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

object (FilterExpression)

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

string (int64 format)

可选。Google Analytics Storage 中起始行的行数。第一行计为第 0 行。

创建报告任务时，offset 和 limit 参数用于定义要纳入所生成报告中的 Google Analytics 存储空间中的数据行子集。例如，如果 Google Analytics 存储空间中共有 30 万行，则初始报告任务的前 1 万行可能具有 1 万的限制和 0 的偏移量。随后，另一个报告任务可以涵盖接下来的 10,000 行，上限为 10,000，偏移量为 10,000。
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 的行。
samplingLevel

enum (SamplingLevel)

可选。报告的抽样级别。

维度

“维度”是指数据的属性。例如，“城市”维度表示事件来自哪个城市。报告响应中的维度值是字符串；例如，城市可以是“巴黎”或“纽约”。

JSON 表示法 
{
  "name": string,
  "dimensionExpression": {
    object (DimensionExpression)
  }
}
字段
name

string

维度的名称。如需查看核心报告方法（例如 runReport 和 batchRunReports）支持的维度名称列表，请参阅 API 维度。如需查看 runRealtimeReport 方法支持的维度名称列表，请参阅实时维度。如需查看 runFunnelReport 方法支持的维度名称列表，请参阅漏斗维度。

如果指定了 dimensionExpression，则 name 可以是允许的字符集中的任何所需字符串。例如，如果 dimensionExpression 连接了 country 和 city，您可以将该维度称为 countryAndCity。您选择的维度名称必须与正则表达式 ^[a-zA-Z0-9_]$ 匹配。

维度在 dimensionFilter、orderBys、dimensionExpression 和 pivots 中由 name 引用。
dimensionExpression

object (DimensionExpression)

一个维度可以是多个维度的表达式的结果。例如，维度“国家/地区、城市”：concatenate(国家/地区, ", ", 城市)。

DimensionExpression

用于表示多个维度的公式的结果维度。使用示例：1) lowerCase(dimension) 2) concatenate(dimension1, symbol, dimension2)。

JSON 表示法 
{

  // Union field one_expression can be only one of the following:
  "lowerCase": {
    object (CaseExpression)
  },
  "upperCase": {
    object (CaseExpression)
  },
  "concatenate": {
    object (ConcatenateExpression)
  }
  // End of list of possible types for union field one_expression.
}
字段
联合字段 one_expression。为 DimensionExpression 指定一种维度表达式。one_expression 只能是下列其中一项：
lowerCase

object (CaseExpression)

用于将维度值转换为小写。
upperCase

object (CaseExpression)

用于将维度值转换为大写。
concatenate

object (ConcatenateExpression)

用于将维度值合并为单个维度。例如，维度“国家/地区、城市”：concatenate(国家/地区, ", ", 城市)。

CaseExpression

用于将维度值转换为单一的大小写形式。

JSON 表示法 
{
  "dimensionName": string
}
字段
dimensionName

string

维度的名称。该名称必须指回请求的维度字段中的某个名称。

ConcatenateExpression

用于将维度值合并为单个维度。

JSON 表示法 
{
  "dimensionNames": [
    string
  ],
  "delimiter": string
}
字段
dimensionNames[]

string

维度的名称。这些名称必须指回请求的维度字段中的名称。
delimiter

string

放置在维度名称之间的分隔符。

分隔符通常是单个字符，例如“|”或“,”，但也可以是较长的字符串。如果维度值包含分隔符，则两者都会显示在响应中，但没有区别。例如，如果维度 1 的值为“US,FR”，维度 2 的值为“JP”，分隔符为“,”，则响应将包含“US,FR,JP”。

指标

报告的量化衡量标准。例如，指标 eventCount 是指事件总数。最多允许请求 10 个指标。

JSON 表示法 
{
  "name": string,
  "expression": string,
  "invisible": boolean
}
字段
name

string

相应指标的名称。如需查看核心报告方法（例如 runReport 和 batchRunReports）支持的指标名称列表，请参阅 API 指标。如需查看 runRealtimeReport 方法支持的指标名称列表，请参阅实时指标。如需查看 runFunnelReport 方法支持的指标名称列表，请参阅漏斗图指标。

如果指定了 expression，则 name 可以是允许的字符集中的任何所需字符串。例如，如果 expression 为 screenPageViews/sessions，则可以将相应指标的名称设为 viewsPerSession。您选择的指标名称必须与正则表达式 ^[a-zA-Z0-9_]$ 匹配。

指标在 metricFilter、orderBys 和指标 expression 中通过 name 进行引用。
expression

string

派生指标的数学表达式。例如，“每位用户的事件数”指标为 eventCount/totalUsers。
invisible

boolean

表示相应指标在报告响应中是否不可见。如果某个指标处于不可见状态，则该指标不会在响应中生成列，但可用于 metricFilter、orderBys 或指标 expression。

DateRange

一组连续的日期：startDate、startDate + 1、...、endDate。最多允许请求 4 个日期范围。

JSON 表示法 
{
  "startDate": string,
  "endDate": string,
  "name": string
}
字段
startDate

string

查询的开始日期（含此日期），格式为 YYYY-MM-DD。不得晚于 endDate。系统也接受 NdaysAgo、yesterday 或 today 格式，在这种情况下，系统会根据媒体资源的报告时区推断日期。
endDate

string

查询的结束日期（含此日期），格式为 YYYY-MM-DD。不得早于 startDate。系统也接受 NdaysAgo、yesterday 或 today 格式，在这种情况下，系统会根据媒体资源的报告时区推断日期。
name

string

为此日期范围分配名称。在报告响应中，维度 dateRange 的值为此名称。如果设置，则不能以 date_range_ 或 RESERVED_ 开头。如果未设置，日期范围将按其在请求中的从零开始的索引命名：date_range_0、date_range_1 等。

FilterExpression

用于表示维度或指标过滤条件。同一 FilterExpression 中的字段必须全部为维度或全部为指标。

JSON 表示法 
{

  // Union field expr can be only one of the following:
  "andGroup": {
    object (FilterExpressionList)
  },
  "orGroup": {
    object (FilterExpressionList)
  },
  "notExpression": {
    object (FilterExpression)
  },
  "filter": {
    object (Filter)
  }
  // End of list of possible types for union field expr.
}
字段
联合字段 expr。为 FilterExpression 指定一种过滤表达式。expr 只能是下列其中一项：
andGroup

object (FilterExpressionList)

andGroup 中的 FilterExpressions 具有 AND 关系。
orGroup

object (FilterExpressionList)

orGroup 中的 FilterExpressions 具有 OR 关系。
notExpression

object (FilterExpression)

FilterExpression 不是 notExpression。
filter

object (Filter)

一种基本过滤条件。在同一 FilterExpression 中，过滤条件的所有字段名称必须全部为维度或全部为指标。

FilterExpressionList

过滤条件表达式列表。

JSON 表示法 
{
  "expressions": [
    {
      object (FilterExpression)
    }
  ]
}
字段
expressions[]

object (FilterExpression)

过滤条件表达式列表。

过滤

用于过滤维度或指标值的表达式。

JSON 表示法 
{
  "fieldName": string,

  // Union field one_filter can be only one of the following:
  "stringFilter": {
    object (StringFilter)
  },
  "inListFilter": {
    object (InListFilter)
  },
  "numericFilter": {
    object (NumericFilter)
  },
  "betweenFilter": {
    object (BetweenFilter)
  },
  "emptyFilter": {
    object (EmptyFilter)
  }
  // End of list of possible types for union field one_filter.
}
字段
fieldName

string

维度名称或指标名称。必须是维度或指标中定义的名称。
联合字段 one_filter。为 Filter 指定一种过滤条件类型。one_filter 只能是下列其中一项：
stringFilter

object (StringFilter)

与字符串相关的过滤条件。
inListFilter

object (InListFilter)

用于过滤列表中的值的过滤条件。
numericFilter

object (NumericFilter)

用于过滤数值或日期值的过滤条件。
betweenFilter

object (BetweenFilter)

用于介于两个值之间的过滤条件。
emptyFilter

object (EmptyFilter)

用于过滤空值（例如“(not set)”和“”)的过滤条件。

StringFilter

字符串过滤条件

JSON 表示法 
{
  "matchType": enum (MatchType),
  "value": string,
  "caseSensitive": boolean
}
字段
matchType

enum (MatchType)

相应过滤条件的匹配类型。
value

string

用于匹配的字符串值。
caseSensitive

boolean

如果为 true，则字符串值区分大小写。

MatchType

字符串过滤器的匹配类型

枚举
MATCH_TYPE_UNSPECIFIED 未指定
EXACT 字符串值完全匹配。
BEGINS_WITH 以字符串值开头。
ENDS_WITH 以字符串值结尾。
CONTAINS 包含字符串值。
FULL_REGEXP 正则表达式与字符串值完全匹配。
PARTIAL_REGEXP 字符串值与正则表达式的部分匹配。

InListFilter

结果需要采用字符串值列表的形式。

JSON 表示法 
{
  "values": [
    string
  ],
  "caseSensitive": boolean
}
字段
values[]

string

字符串值列表。不得为空。
caseSensitive

boolean

如果为 true，则字符串值区分大小写。

NumericFilter

用于过滤数值或日期值。

JSON 表示法 
{
  "operation": enum (Operation),
  "value": {
    object (NumericValue)
  }
}
字段
operation

enum (Operation)

相应过滤器的操作类型。
value

object (NumericValue)

数值或日期值。

操作

应用于数值过滤条件的运算

枚举
OPERATION_UNSPECIFIED 未指定。
EQUAL 等于
LESS_THAN 小于
LESS_THAN_OR_EQUAL 小于或等于
GREATER_THAN 大于
GREATER_THAN_OR_EQUAL 大于或等于

NumericValue

表示一个数字。

JSON 表示法 
{

  // Union field one_value can be only one of the following:
  "int64Value": string,
  "doubleValue": number
  // End of list of possible types for union field one_value.
}
字段
联合字段 one_value。数值 one_value 只能是以下值之一：
int64Value

string (int64 format)

整数值
doubleValue

number

DoubleValue

BetweenFilter

表示结果必须介于两个数字之间（含这两个数字）。

JSON 表示法 
{
  "fromValue": {
    object (NumericValue)
  },
  "toValue": {
    object (NumericValue)
  }
}
字段
fromValue

object (NumericValue)

以该数字开头。
toValue

object (NumericValue)

以该数字结尾。

EmptyFilter

此类型没有字段。

过滤空值。

MetricAggregation

表示指标的汇总。

枚举
METRIC_AGGREGATION_UNSPECIFIED 未指定运算符。
TOTAL SUM 运算符。
MINIMUM 最小值运算符。
MAXIMUM 最大值运算符。
COUNT Count 运算符。

OrderBy

排序依据定义了响应中各行的排序方式。例如，按事件数降序对行进行排序是一种排序方式，而按事件名称字符串对行进行排序则是另一种排序方式。

JSON 表示法 
{
  "desc": boolean,

  // Union field one_order_by can be only one of the following:
  "metric": {
    object (MetricOrderBy)
  },
  "dimension": {
    object (DimensionOrderBy)
  }
  // End of list of possible types for union field one_order_by.
}
字段
desc

boolean

如果为 true，则按降序排序。
联合字段 one_order_by。为 OrderBy 指定一种排序依据类型。one_order_by 只能是下列其中一项：
metric

object (MetricOrderBy)

按指标值对结果进行排序。
dimension

object (DimensionOrderBy)

按维度值对结果进行排序。

MetricOrderBy

按指标值排序。

JSON 表示法 
{
  "metricName": string
}
字段
metricName

string

请求中用于排序的指标名称。

DimensionOrderBy

按维度值排序。

JSON 表示法 
{
  "dimensionName": string,
  "orderType": enum (OrderType)
}
字段
dimensionName

string

请求中用于排序的维度名称。
orderType

enum (OrderType)

控制维度值排序的规则。

OrderType

用于对字符串维度值进行排序的规则。

枚举
ORDER_TYPE_UNSPECIFIED 未指定。
ALPHANUMERIC 按 Unicode 码位进行字母数字排序。例如，“2”<“A”<“X”<“b”<“z”。
CASE_INSENSITIVE_ALPHANUMERIC 按小写 Unicode 码位进行不区分大小写的字母数字排序。例如，“2”<“A”<“b”<“X”<“z”。
NUMERIC 维度值会在排序之前转换为数字。例如，在“数字”排序中，“25”小于“100”，而在 ALPHANUMERIC 排序中，“100”小于“25”。所有非数值维度值的排序值都相等，且低于所有数值维度值。

CohortSpec

同类群组报告的同类群组规范。

同类群组报告会针对同类群组创建用户留存率时间序列。例如，您可以选择 9 月第一周赢得的用户组成的同类群组，并在接下来的六周内跟踪该同类群组。在 cohort 对象中指定了选择 9 月第一周获取的用户同类群组。cohortsRange 对象中指定了在接下来六周内跟踪该群组。

如需查看示例，请参阅同类群组报告示例。

报告响应可能会显示每周时间序列，例如，您的应用在三周后留住了该群组中 60% 的用户，在六周后留住了该群组中 25% 的用户。这两个百分比可以通过指标 cohortActiveUsers/cohortTotalUsers 计算得出，并会显示在报告中的不同行中。

JSON 表示法 
{
  "cohorts": [
    {
      object (Cohort)
    }
  ],
  "cohortsRange": {
    object (CohortsRange)
  },
  "cohortReportSettings": {
    object (CohortReportSettings)
  }
}
字段
cohorts[]

object (Cohort)

定义将用户分组到同类群组中的选择条件。

大多数同类群组报告仅定义一个同类群组。如果指定了多个同类群组，则可以在报告中按名称识别每个同类群组。
cohortsRange

object (CohortsRange)

同类群组报告会在较长的报告日期范围内跟踪同类群组。此范围指定了用于跟踪同类群组的偏移时长。
cohortReportSettings

object (CohortReportSettings)

同类群组报告的可选设置。

同类群组

定义一种同群组选择条件。同类群组是具有共同特征的一组用户。例如，firstSessionDate 相同的用户属于同一同类群组。

JSON 表示法 
{
  "name": string,
  "dimension": string,
  "dateRange": {
    object (DateRange)
  }
}
字段
name

string

为此群组分配名称。在报告响应中，维度 cohort 的值为此名称。如果设置，则不能以 cohort_ 或 RESERVED_ 开头。如果未设置，则根据从零开始的指数 cohort_0、cohort_1 等为同类群组命名。
dimension

string

同类群组使用的维度。必需，且仅支持 firstSessionDate。
dateRange

object (DateRange)

同类群组会选择首次接触日期介于 dateRange 中定义的开始日期和结束日期之间的用户。此 dateRange 未指定同类群组报告中显示的事件数据的完整日期范围。在同类群组报告中，此 dateRange 会根据 cohortsRange 中的粒度和偏移量进行扩展；扩展后的报告日期范围对应的事件数据会显示在同类群组报告中。

在同类群组请求中，此 dateRange 是必需的，并且 RunReportRequest 或 RunPivotReportRequest 中的 dateRanges 必须未指定。

此 dateRange 通常应与同群组的粒度保持一致。如果 CohortsRange 使用的是每日粒度，则此 dateRange 可以是单日。如果 CohortsRange 使用的是每周粒度，则此 dateRange 可以与周边界对齐，从周日开始到周六结束。如果 CohortsRange 使用的是月级粒度，则此 dateRange 可以与一个月对齐，从当月的第一天开始，到当月的最后一天结束。

CohortsRange

为同类群组报告配置扩展报告日期范围。指定要跟踪的同类群组的偏移时长。

JSON 表示法 
{
  "granularity": enum (Granularity),
  "startOffset": integer,
  "endOffset": integer
}
字段
granularity

enum (Granularity)

必需。用于解读同类群组报告的扩展报告日期范围的 startOffset 和 endOffset 的粒度。
startOffset

integer

startOffset 用于指定同类群组报告的扩展报告日期范围的开始日期。startOffset 通常设置为 0，以便报告包含从相应同群组的获取日期开始的数据。

如果 granularity 为 DAILY，则扩展报告日期范围的 startDate 为同类群组的 startDate 加上 startOffset 天。

如果 granularity 为 WEEKLY，则扩展报告日期范围的 startDate 为同类群组的 startDate 加上 startOffset * 7 天。

如果 granularity 为 MONTHLY，则扩展报告日期范围的 startDate 为同类群组的 startDate 加上 startOffset * 30 天。
endOffset

integer

必需。endOffset 用于指定同类群组报告的扩展报告日期范围的结束日期。endOffset 可以是任何正整数，但通常设置为 5 到 10，以便报告包含未来几个时间粒度的时间段的同类群组数据。

如果 granularity 为 DAILY，则扩展报告日期范围的 endDate 为同类群组的 endDate 加上 endOffset 天。

如果 granularity 为 WEEKLY，则扩展报告日期范围的 endDate 为同类群组的 endDate 加上 endOffset * 7 天。

如果 granularity 为 MONTHLY，则扩展报告日期范围的 endDate 为同类群组的 endDate 加上 endOffset * 30 天。

粒度

用于解读同类群组报告的扩展报告日期范围的 startOffset 和 endOffset 的粒度。

枚举
GRANULARITY_UNSPECIFIED 切勿指定。
DAILY 每日粒度。如果群组的 dateRange 为单日，且请求包含 cohortNthDay，则通常使用此值。
WEEKLY 每周粒度。如果群组的 dateRange 为一周（从周日开始到周六结束），且请求包含 cohortNthWeek，则通常使用此函数。
MONTHLY 每月粒度。如果相应群组的 dateRange 为一个月，且请求包含 cohortNthMonth，则通常使用此值。

CohortReportSettings

同类群组报告的可选设置。

JSON 表示法 
{
  "accumulate": boolean
}
字段
accumulate

boolean

如果为 true，则从首次触达日期到结束日期累积结果。在 RunReportRequest 中不支持。

SamplingLevel

请求的抽样级别类别。

枚举
SAMPLING_LEVEL_UNSPECIFIED 未指定的类型。
LOW 对标准媒体资源应用 1,000 万的抽样级别，对 Google Analytics 360 媒体资源应用 1 亿的抽样级别。
MEDIUM 仅适用于抽样级别为 10 亿的 Google Analytics 360 媒体资源。
UNSAMPLED 仅适用于 Google Analytics 360 媒体资源。非抽样探索更加准确，可以揭示在标准探索中无法看到的数据分析。如需了解详情，请参阅 https://support.google.com/analytics/answer/10896953。

ReportMetadata

特定报告任务的报告元数据。

JSON 表示法 
{
  "creationQuotaTokensCharged": integer,
  "state": enum (State),
  "beginCreatingTime": string,
  "taskRowCount": integer,
  "errorMessage": string,
  "totalRowCount": integer
}
字段
creationQuotaTokensCharged

integer

仅限输出。生成报告期间收取的配额令牌总数。由于此令牌数基于 CREATING 状态的活动，因此一旦报告任务进入 ACTIVE 或 FAILED 状态，此令牌费用就会固定下来。
state

enum (State)

仅限输出。相应报告任务的当前状态。
beginCreatingTime

string (Timestamp format)

仅限输出。调用 reportTasks.create 的时间，以及报告开始进入 CREATING 状态的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
taskRowCount

integer

仅限输出。报告结果中的总行数。当状态为有效时，系统会填充此字段。您可以在现有报告的范围内利用 taskRowCount 进行分页。
errorMessage

string

仅限输出。如果报告任务在创建期间失败，则填充错误消息。
totalRowCount

integer

仅限输出。Google Analytics 存储空间中的总行数。如果您想查询当前报告之外的其他数据行，可以根据 totalRowCount 启动新的报告任务。

taskRowCount 表示与当前报告相关的行数，而 totalRowCount 则表示从 Google Analytics 存储空间检索到的所有数据的总行数。

例如，假设当前报告的 taskRowCount 为 20，则显示前 20 行的数据。与此同时，totalRowCount 为 30，表示所有 30 行都有数据。taskRowCount 可用于对前 20 行进行分页。如需展开报告并纳入所有 30 行的数据，可以使用 totalRowCount 创建新的报告任务，以访问包含 30 行数据的完整数据集。

州

处理状态。

枚举
STATE_UNSPECIFIED 系统绝不会使用未指定状态。
CREATING 报告目前正在创建中，将在未来提供。创建会在调用 CreateReport 后立即进行。
ACTIVE 报告已完全创建，可以进行查询。
FAILED 未能创建报告。

方法

create

 启动报告任务的创建。

get

 获取有关特定报告任务的报告元数据。

list

 列出媒体资源的所有报告任务。

query

 检索报告任务的内容。