REST Resource: properties.reportTasks

{
  "name": string,
  "reportDefinition": {
    object (ReportDefinition)
  },
  "reportMetadata": {
    object (ReportMetadata)
  }
}

string

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

object (ReportDefinition)

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

object (ReportMetadata)

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

{
  "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
}

object (Dimension)

可选。请求和显示的维度。

object (Metric)

可选。请求和显示的指标。

object (DateRange)

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

object (FilterExpression)

可选。借助维度过滤条件，您可以只在报告中使用特定的维度值。要了解详情，请参阅维度过滤条件基础知识中的相关示例。此过滤条件中不能使用指标。

object (FilterExpression)

可选。指标的过滤条件子句。在对报告的数据行进行汇总后应用，类似于 SQL 子句。维度不能在此过滤条件中使用。

string (int64 format)

可选。Google Analytics（分析）存储空间中起始行的行数。第一行计为第 0 行。

创建报告任务时，offset 和 limit 参数定义要包含在生成的报告中的 Google Analytics（分析）存储空间中的数据行子集。例如，如果 Google Analytics（分析）存储空间总共有 30 万行，则初始报告任务的前 10000 行，上限为 10,000 行，偏移量为 0。随后，另一个报告任务可以涵盖接下来的 10,000 行，但上限为 10,000，偏移为 10,000。

string (int64 format)

可选。报告中要返回的行数。如果未指定，将返回 10,000 行。无论您请求返回多少行，每个请求最多返回 250,000 行。“limit”必须为正数。

如果维度值没有 limit 多，API 返回的行数也可能小于请求的 limit。例如，如果维度“country”的可能值少于 300 个，那么，在仅针对“country”生成报表时，即使您将 limit 设为更高的值，所得到的行数也不能超过 300 行。

enum (MetricAggregation)

可选。指标聚合。汇总的指标值将在“dimensionValues”设置为“RESERVED_(MetricAggregation)”的行中显示。

object (OrderBy)

可选。指定响应中行的排序方式。

string

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

object (CohortSpec)

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

boolean

可选。如果为 false 或未指定，则不会返回所有指标都等于 0 的每一行。如果为 true，则返回这些行（前提是它们未被过滤器单独移除）。

无论这项 keepEmptyRows 设置如何，只有 Google Analytics（分析）(GA4) 媒体资源记录的数据才会显示在报告中。

例如，如果某个媒体资源从未记录过 purchase 事件，则针对“eventName”维度和 eventCount 指标的查询将不会有包含 eventName：“purchase”和 eventCount：0 的行。

{
  "name": string,
  "dimensionExpression": {
    object (DimensionExpression)
  }
}

string

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

如果指定了 dimensionExpression，则 name 可以是您希望在允许的字符集中添加的任何字符串。例如，如果 dimensionExpression 将 country 和 city 串联在一起，您可以调用该维度 countryAndCity。您选择的维度名称必须与正则表达式 ^[a-zA-Z0-9_]$ 匹配。

尺寸由 name 在 dimensionFilter、orderBys、dimensionExpression 和 pivots 中引用。

object (DimensionExpression)

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

{

  // 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.
}

object (CaseExpression)

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

object (CaseExpression)

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

object (ConcatenateExpression)

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

{
  "dimensionName": string
}

string

维度名称。该名称必须引用请求的维度字段中的名称。

{
  "dimensionNames": [
    string
  ],
  "delimiter": string
}

string

维度名称。这些名称必须引用请求的维度字段中的名称。

string

维度名称之间的分隔符。

分隔符通常是单个字符，例如“|”或“,”，但也可以是较长的字符串。如果某个维度值包含分隔符，则这两个分隔符都会出现在响应中，不会有任何区别。例如，如果维度 1 的值 =“US,FR”，维度 2 的值 =“JP”，分隔符 =“,”，则响应将包含“US,FR,JP”。

{
  "name": string,
  "expression": string,
  "invisible": boolean
}

string

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

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

指标由 metricFilter、orderBys 和 expression 中的 name 引用。

string

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

boolean

指明指标是否在报告响应中不可见。如果指标不可见，则该指标不会在响应中生成列，但可以在 metricFilter、orderBys 或 expression 中使用。

{
  "startDate": string,
  "endDate": string,
  "name": string
}

string

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

string

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

string

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

{

  // 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.
}

object (FilterExpressionList)

andGroup 中的 FilterExpressions 具有 AND 关系。

object (FilterExpressionList)

orGroup 中的 FilterExpressions 具有 OR 关系。

object (FilterExpression)

FilterExpression 不是 notExpression。

object (Filter)

初始过滤器。在同一 FilterExpression 中，过滤器的所有字段名称都需要是所有维度或所有指标。

{
  "expressions": [
    {
      object (FilterExpression)
    }
  ]
}

object (FilterExpression)

过滤条件表达式列表。

{
  "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)
  }
  // End of list of possible types for union field one_filter.
}

string

维度名称或指标名称。必须是维度或指标中定义的名称。

object (StringFilter)

字符串相关过滤条件。

object (InListFilter)

列表值中的过滤器。

object (NumericFilter)

数字或日期值的过滤条件。

object (BetweenFilter)

两个值之间的过滤条件。

{
  "matchType": enum (MatchType),
  "value": string,
  "caseSensitive": boolean
}

enum (MatchType)

此过滤器的匹配类型。

string

用于匹配的字符串值。

boolean

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

{
  "values": [
    string
  ],
  "caseSensitive": boolean
}

string

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

boolean

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

{
  "operation": enum (Operation),
  "value": {
    object (NumericValue)
  }
}

enum (Operation)

此过滤器的操作类型。

object (NumericValue)

数值或日期值。

{

  // 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.
}

string (int64 format)

整数值

number

DoubleValue

{
  "fromValue": {
    object (NumericValue)
  },
  "toValue": {
    object (NumericValue)
  }
}

object (NumericValue)

以此数字开头。

object (NumericValue)

以此数字结尾。

{
  "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.
}

boolean

如果为 true，则按降序排序。

object (MetricOrderBy)

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

object (DimensionOrderBy)

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

{
  "metricName": string
}

string

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

{
  "dimensionName": string,
  "orderType": enum (OrderType)
}

string

请求排序依据的维度名称。

enum (OrderType)

控制维度值排序规则。

{
  "cohorts": [
    {
      object (Cohort)
    }
  ],
  "cohortsRange": {
    object (CohortsRange)
  },
  "cohortReportSettings": {
    object (CohortReportSettings)
  }
}

object (Cohort)

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

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

object (CohortsRange)

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

object (CohortReportSettings)

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

{
  "name": string,
  "dimension": string,
  "dateRange": {
    object (DateRange)
  }
}

string

为该同类群组指定名称。在报告响应中，维度 cohort 使用此名称。如果设置了此字段，则不能以 cohort_ 或 RESERVED_ 开头。如果未设置此字段，同类群组将按其从零开始的索引 cohort_0、cohort_1 等命名。

string

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

object (DateRange)

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

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

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

{
  "granularity": enum (Granularity),
  "startOffset": integer,
  "endOffset": integer
}

enum (Granularity)

必需。一个粒度，用于解读同类群组报告中较长报告日期范围内的startOffset和endOffset。

integer

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

如果“granularity”为“DAILY”，则延长的报告日期范围的startDate为同类群组的 startDate 外加 startOffset 天。

如果“granularity”为“WEEKLY”，则延长的报告日期范围的startDate为同类群组的 startDate 外加 startOffset * 7 天。

如果“granularity”为“MONTHLY”，则延长的报告日期范围的startDate为同类群组的 startDate 外加 startOffset * 30 天。

integer

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

如果“granularity”为“DAILY”，则延长的报告日期范围的endDate为同类群组的 endDate 外加 endOffset 天。

如果“granularity”为“WEEKLY”，则延长的报告日期范围的endDate为同类群组的 endDate 外加 endOffset * 7 天。

如果“granularity”为“MONTHLY”，则延长的报告日期范围的endDate为同类群组的 endDate 外加 endOffset * 30 天。

{
  "accumulate": boolean
}

boolean

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

{
  "creationQuotaTokensCharged": integer,
  "state": enum (State),
  "beginCreatingTime": string,
  "taskRowCount": integer,
  "errorMessage": string,
  "totalRowCount": integer
}

integer

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

enum (State)

仅限输出。此报告任务的当前状态。

string (Timestamp format)

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

采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式的时间戳，采用纳秒级精度，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

integer

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

string

仅限输出。如果报告任务在创建过程中失败，系统会填充错误消息。

integer

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

taskRowCount 表示与当前报告明确有关的行数，而 totalRowCount 包括从 Google Analytics（分析）存储空间检索到的所有数据的总行数。

例如，假设当前报告的 taskRowCount 为 20，显示前 20 行的数据。同时，totalRowCount 为 30，表示所有 30 行数据都存在。taskRowCount 可用于对前 20 行进行分页。要展开报告并纳入全部 30 行的数据，可以使用 totalRowCount 来创建新的报告任务，以访问全部 30 行数据。