本指南介绍了 Chrome 用户体验报告 (CrUX) History API 端点，该端点提供时间序列的 Web 性能数据。这些数据每周更新一次，可让您查看大约 6 个月的历史数据，其中包含 25 个数据点，每个数据点相隔一周。
与原始 CrUX API 端点中的每日更新搭配使用时，您现在可以快速查看最新数据和之前发生的情况，这是一个强大的工具，可用于查看网页随时间推移而发生的变化。
在此页面上试用 API
查询每日 CrUX API
如需回顾上一篇介绍 CrUX API 的文章，您可以通过以下方式获取特定来源的字段数据快照：
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
此快照包含特定 28 天收集期的直方图密度值和百分位数值，在本例中，该时间段为 2022 年 12 月 27 日至 2023 年 1 月 23 日。
查询 CrUX History API
如需调用历史记录端点，请在 curl 命令中将网址中的 queryRecord 更改为 queryHistoryRecord。使用与上次调用相同的 CrUX API 密钥即可。
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
响应的整体结构类似，但包含的数据要多得多！现在，包含第 75 百分位数 (p75) 和直方图密度值的字段不再是单个数据点，而是时间序列。
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
在此示例中，Largest Contentful Paint (LCP) 指标的 0 到 2500 毫秒分桶的 densities 时间序列为 [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].。这些密度是在相应的 collectionPeriods 条目期间观察到的。例如，第五个密度值 0.9183 是截至 2022 年 9 月 3 日的第五个收集周期的密度值，而 0.9187 是截至次周结束的周期的密度值。
换句话说，解读示例中 https://web.dev 的最后时间序列条目后，我们发现从 2022 年 8 月 14 日到 2022 年 9 月 10 日，91.87% 的网页加载的 LCP 值小于 2500 毫秒，5.27% 的值介于 2500 毫秒到 4000 毫秒之间，2.85% 的值大于 4000 毫秒。
同样，P75 值也有时间序列：2022 年 8 月 14 日至 2022 年 9 月 10 日的 LCP P75 为 1377。这意味着，在相应收集期间，75% 的用户体验的 LCP 低于 1377 毫秒，25% 的用户体验的 LCP 高于 1377 毫秒。
虽然该示例仅列出了 6 个时间序列条目和收集周期，但 API 的响应提供了 25 个时间序列条目；由于这些收集周期的结束日期都是相隔 7 天的星期六，因此这涵盖了 6 个月的时间范围。
在任何给定响应中，直方图分箱密度和 p75 值的时间序列长度将与 collectionPeriods 字段中的数组长度完全相同：这些数组的索引之间存在一对一对应关系。
查询网页级数据
除了来源级数据之外，CrUX History API 还允许访问历史网页级数据。虽然您之前可以使用 BigQuery 中的 CrUX 数据集（或使用 CrUX 信息中心）获取来源级数据，但只有在网站自行收集和存储页面级历史数据的情况下，您才能获取此类数据。现在，新 API 可以解锁这些历史网页级数据。
您可以以相同的方式查询网页级数据，但在载荷中使用 url 而非 origin：
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
网页级（和来源级）历史数据需满足与 CrUX 的其余部分相同的资格要求，因此网页可能没有完整的历史记录。在这些情况下，“缺失”数据将由 "NaN"（对于 histogramTimeseries 密度）和 null（对于 percentilesTimeseries）表示。之所以会出现这种差异，是因为直方图密度始终是数字，而百分比可以是数字或字符串（CLS 使用字符串，即使它们看起来像数字也是如此）。
可视化数据
因此，您可能会问，为什么数据的格式是这样的？我们发现，这样可以更轻松地绘制图表。例如，下图显示了 https://web.dev 的 Interaction To Next Paint (INP) 的 p75 值：
在此折线图中，y 轴上的每个值都是 p75s 时间序列中的第 75 个百分位数值，x 轴是时间，每个收集周期的 lastDate 均设置为此值。
下面是直方图分箱时间序列的图表，也称为三分箱图表，因为这些直方图有三个分箱。
X 轴设置为每个收集周期的 lastDate。不过，这次 y 轴是指 INP 指标在特定范围内的网页加载次数所占的百分比，以堆叠条形图的形式显示。p75 图表可快速概览数据，并且在单个图表中，您可以相对轻松地添加多个指标，或同时显示 PHONE 和 DESKTOP 的线条。三分位图可让您大致了解每个收集周期内测量的指标值的分布情况。
例如，尽管 p75 图表显示 https://web.dev 在观察期间的 INP 值几乎可接受，但三分位图表显示，对于一小部分网页加载，INP 实际上很差。从这两张图表中，我们可以相对轻松地推断出，性能出现了回归问题，该问题从 10 月底开始，并在 11 月中旬得到了修正。
如需自行生成此类图表，我们创建了一个 Colab 示例。借助 Colab（也称为“Colaboratory”），您可在浏览器中编写和执行 Python 代码。CrUX History API Colab（来源）使用 Python 调用 API 并绘制数据图表。
通过此 Colab，您只需填写一份简短的表单，即可创建 p75 图表、三分位图表、以表格形式获取数据，以及查看 CrUX API 的请求和响应对。您无需是程序员即可使用此功能，但您当然可以查看 Python 代码并将其修改为令人惊叹的功能！祝您使用愉快！欢迎随时就您发现的问题提供反馈！
当然，您不局限于使用 Colab 或 Python，这只是如何使用以下新 API 的一个示例。作为基于 JSON 的 HTTP 端点，该 API 可通过任何技术进行查询。
总结
在 CrUX History API 端点推出之前，网站所有者只能从 CrUX 获取有限的历史信息。您可以使用 BigQuery 和 CrUX 信息中心查看来源级月度数据，但无法查看周数据或网页级历史数据。网站所有者可以使用 Daily API 自行记录此类数据，但通常只有在指标出现回归后，才会发现需要这样做。
我们希望通过引入 CrUX History API，让网站所有者能够更好地了解其不断变化的网站指标，并在出现问题时作为诊断工具。如果您使用的是新 API，欢迎在 Chrome UX Report（讨论）Google 群组中提供反馈。
致谢
主打图片：Unsplash 上的 Dave Herring