本指南介绍了 Chrome UX Report (CrUX) History API 端点，此端点提供以时序显示的网页性能数据。这些数据每周更新一次，可让您了解大约 6 个月的历史记录，并以每周为间隔提供 25 个数据点。
现在，与原始 CrUX 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 毫秒到 4200 毫秒，
同样，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 相同的资格要求，因此特别是网页可能没有完整的历史记录。在这些情况下，“缺失的”对于 histogramTimeseries 密度，数据将由 "NaN" 表示；对于 percentilesTimeseries，数据将由 null 表示。出现差异的原因是直方图密度始终是数字，而百分位数可以是数字或字符串（CLS 使用字符串，即使它们看起来像数字）。
直观呈现数据
因此，您可能会问，为什么数据要以这种方式形成？人们发现，这可以更轻松地绘制图表。例如，下图显示了 https://web.dev 上 Interaction To Next Paint (INP) 的 p75 值：
在此折线图中，y 轴上的每个值都是来自 p75s 时序的 p75 值，x 轴是时间，它们被设置为每个收集期的 lastDate。
这是直方图分箱时序的图表（称为三分箱图表），因为这些直方图有三个分箱。
x 轴设置为每个收集期的 lastDate。不过，这次 y 轴是 INP 指标在特定范围内的网页加载次数所占的百分比，通过堆叠条形图显示。通过 P75 图表，您可以快速了解下图表的概况，同时，在单个图表中添加多个指标或同时显示 PHONE 和 DESKTOP 折线相对比较简单。三分箱图表可让您了解每个收集期测量的指标值的分布情况。
例如，虽然 p75 图表显示 https://web.dev 在观察期内的 INP 值几乎可以接受，但 tri-bin 图表显示，对于一小部分网页加载，INP 实际上糟糕。在这两个图表中，比较容易推断出性能下降的情况始于 10 月底，并于 11 月中旬得到解决。
为了能够自行生成此类图表，我们创建了一个示例 Colab。Colab（简称“Colaboratory”）可让您在浏览器中编写和执行 Python 代码。CrUX History API Colab（来源）使用 Python 调用该 API 并绘制数据图表。
借助此 Colab，您可以制作 p75 图表和 tri-bin 图表，以表格形式获取数据，并通过填写一份简短的表单查看 CrUX API 的请求和响应对。即使您不是程序员也能使用它，但您可以查看 Python 代码并将其修改为令人惊叹的内容！请尽情享受，并随时欢迎你提供反馈！
当然，您可以使用并不仅限于 Colab 或 Python，这只是如何使用这一新 API 的一个示例。该 API 是基于 JSON 的 HTTP 端点，可通过任何技术查询。
总结
在引入 CrUX History API 端点之前，网站所有者从 CrUX 获取的历史信息有限。通过 BigQuery 和 CrUX 信息中心可获取每月源级数据，但无法提供每周数据，也无法提供网页级历史数据。网站所有者可以使用每日 API 自行记录这些数据，但通常情况下，只有在指标回归后，他们才会发现这种需求。
推出这个 CrUX History API 是希望它让网站所有者更好地了解其不断变化的网站指标，并作为出现问题时的诊断工具。如果您使用的是新 API，欢迎通过 Chrome 用户体验报告（讨论）Google 群组提供反馈。
致谢
主打图片（作者：Dave Herring，制作者：Dave Herring）