您可以使用 Google Analytics（分析）Data API v1 生成数据透视表。数据透视表是一种数据摘要工具，可以通过按一个或多个维度透视（旋转）数据来重新排列表格中的信息，从而直观呈现数据。
例如，请参考以下原始数据表：
使用此数据可以构建数据透视表，以按浏览器细分会话数据，并选择国家/地区和语言维度作为额外的数据透视。
包含核心报告的共享功能
对于许多共享功能，数据透视报告请求与核心报告请求具有相同的语义。例如，分页、维度过滤条件和用户属性在数据透视报告中的行为与核心报告相同。本指南将着重介绍数据透视报告功能。如需熟悉 Data API v1 的核心报告功能，请参阅报告基础知识指南以及高级用例指南。
透视报表方法
Data API v1 在以下报告方法中支持数据透视功能：
runPivotReport：此方法会返回 Google Analytics（分析）事件数据的自定义数据透视报告。每个数据透视都描述了报告响应中的可见维度列和行。
batchRunPivotReports：此方法是
runPivotReport方法的批处理版本，允许使用单个 API 调用生成多个报告。
选择举报实体
Data API v1 的所有方法都需要在网址请求路径中以 properties/GA4_PROPERTY_ID 的形式指定 Google Analytics（分析）4 媒体资源标识符，例如：
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
所生成的报告将根据在指定的 Google Analytics（分析）4 媒体资源中收集的 Google Analytics（分析）事件数据生成。
如果您使用的是 Data API 客户端库之一，则无需手动操作请求网址路径。大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA4_PROPERTY_ID 形式的字符串。如需查看有关如何使用客户端库的示例，请参阅快速入门指南。
数据透视报表请求
如需使用数据透视表构建请求，请使用 runPivotReport 或 batchRunPivotReports 方法。
如需请求透视数据，您可以构建一个 RunPivotReportRequest 对象。我们建议从以下请求参数开始：
- dateRanges 字段中的有效条目。
- 维度字段中至少有一个有效条目。
- metrics 字段中至少有一个有效条目。
- 数据透视表字段中至少包含 2 个有效的数据透视条目。
以下是包含建议字段的示例请求：
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
数据透视
使用请求正文的 pivot 字段中的 数据透视表对象来定义报告数据透视。每个 Pivot 都描述了报告响应中的可见维度列和行。
Data API v1 支持多个数据透视，前提是每个数据透视的 limit 参数的乘积不超过 100,000。
以下代码段演示了如何使用 pivots 按国家/地区生成会话数报告，并按 browser 维度透视数据。请注意该查询如何使用 orderBys 字段进行排序，以及使用 limit 和 offset 字段来实现分页。
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
维度
维度用于描述网站或应用的事件数据并对其进行分组。例如，city 维度表示每个事件的发起城市（“巴黎”或“纽约”）。在报告请求中，您可以指定零个或多个维度。
必须在请求正文的 dimensions 字段内定义维度。若要在报告中查看，这些维度还必须列在 Pivot 对象的 fieldNames 字段中。如果某个维度未用于数据透视查询的任何数据透视，则不会显示在报告中。并非每个维度都必须存在于数据透视的 fieldNames 中。维度只能用在过滤器中，不能用在任何数据透视的 fieldNames 中。
以下代码段演示了如何为包含 browser、country 和 language 数据透视的表使用 dimension 和 fieldNames 字段：
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
指标
指标是对网站或应用的事件数据的量化衡量标准。在报告请求中，您可以指定一个或多个指标。如需查看可在请求中指定的 API 指标名称的完整列表，请参阅 API 指标。
在数据透视报告请求中，指标是使用请求正文的 metrics 字段定义的，该字段类似于核心报告方法。
以下示例指定了在报告中用作指标值的会话数：
"metrics": [
{
"name": "sessions"
}
],
指标汇总
使用 数据透视表对象的 metricAggregations 字段计算每个数据透视的汇总指标值。
只有在请求中指定 metricAggregations 字段时，系统才会计算聚合值。
以下是请求 browser 数据透视维度总数的查询代码段：
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
计算指标在 RunPivotReportResponse 对象的 aggregates 字段中返回。对于汇总指标行，dimensionValues 字段包含特殊值 RESERVED_TOTAL、RESERVED_MAX 或 RESERVED_MIN。
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
分页
与核心报告方法类似，数据透视请求允许您在 数据透视表对象中指定 limit 和 offset 字段来实现分页。分页设置会分别应用于每个数据透视。
每个 Pivot 对象都需要 limit 字段，以限制报告基数。
Data API v1 支持多个数据透视，前提是每个数据透视的 limit 参数的乘积不超过 100,000。
以下代码段演示了如何使用 offset 和 limit 字段检索接下来的 5 个 language 维度（偏移量为 10）：
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
过滤
与 Core Reporting 功能类似，如果数据透视报告请求中需要维度过滤，则必须使用请求级范围的维度过滤条件。
排序
使用 orderBys对象（其中包含 OrderBy 对象列表）的 orderBys 字段可以单独控制每个数据透视报告查询的排序行为。
每个 OrderBy 都可以包含以下内容之一：
- DimensionOrderBy，按维度值对结果进行排序。
- MetricOrderBy，按指标值对结果进行排序。
- PivotOrderBy，用于数据透视查询，可按数据透视列组中的指标值对结果进行排序。
此示例展示的数据透视定义的代码段根据 browser 维度透视报告，并按 sessions 指标降序对结果进行排序。
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
报告响应
数据透视报告 API 请求的数据透视报告响应主要是标题和行。
响应标头
数据透视报告标题由 PivotHeaders、DimensionHeaders 和 MetricHeaders 组成，用于列出数据透视报告中的列。
例如，具有 browser、country 和 language 数据透视维度以及 sessions 指标的报告将生成如下标题：
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
下图说明了数据透视报告响应的每个组件在呈现数据透视报告时的作用：
响应行数
runPivotReport 和 batchRunPivotReports 方法的响应与核心报告方法（例如 runReport 和 batchRunReports）的响应不同，每个数据透视报告响应行代表表格的单个单元格，而在常规报告中，单个响应行代表完整的表格行。
以下是包含 browser、country 和 language 数据透视维度以及 sessions 指标的查询的数据透视报告响应的片段。系统会分别返回数据透视报告的每个单元格：
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
此数据对应于下表中突出显示的两个单元格：
客户端库
以下示例使用 Python 客户端库运行数据透视查询，以按国家/地区生成会话数报告，并按浏览器维度透视数据。
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
演示应用
有关如何使用 JavaScript 构建和显示数据透视报告的示例，请参阅 Google Analytics（分析）API v1 数据透视报告演示应用。