发布时间：2023 年 2 月 7 日；上次更新时间：2025 年 4 月 11 日
本指南介绍了 Chrome 用户体验报告 (CrUX) History API 端点，该端点提供时间序列的网络性能数据。这些数据每周更新一次，可让您查看大约 6 个月的历史数据，其中包含 40 个数据点，每个数据点相隔一周。
与原始 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 密钥即可。collectionPeriodCount 用于指定要返回的时间序列条目数；上限为 40。如果未指定，则默认为 25。
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", "collectionPeriodCount": 40}'
响应的整体结构类似，但包含的数据要多得多！现在，包含第 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 个时间序列条目，如果请求中指定了 "collectionPeriodCount": 40，则最多可提供 40 个。由于这些收集周期的结束日期都是相隔 7 天的星期六，因此对于 "collectionPeriodCount": 40，这涵盖了 10 个月。
在任何给定响应中，直方图分箱密度和 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 使用字符串，即使它们看起来像数字也是如此）。
可视化数据
可视化数据的最简单方法是使用 CrUX Vis，这是一个专门用于演示 CrUX History API 强大功能的工具。如需了解详情，请参阅 CrUX 可视化文档。
如需自行生成类似的图表，我们创建了一个 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 信息中心查看来源级月度数据，但无法查看周数据或网页级历史数据。网站所有者可以使用每日 API 自行记录此类数据，但通常只有在指标出现回归后，才会发现需要这样做。
我们希望通过引入 CrUX History API，网站所有者能够更好地了解其不断变化的网站指标，并在出现问题时将其用作诊断工具。如果您使用的是新 API，欢迎在 Chrome UX Report（讨论）Google 群组中提供反馈。
致谢
主打图片：Unsplash 上的 Dave Herring