本指南介绍了 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 毫秒到 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 的其余部分相同的资格要求，因此网页可能没有完整的历史记录。在这些情况下，“缺失”的数据将由 "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 值几乎可以接受，但 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 信息中心查看来源级月度数据，但无法查看周数据或网页级历史数据。网站所有者可以使用 Daily API 自行记录此类数据，但通常只有在指标出现回归后，才会发现需要这样做。
推出这个 CrUX History API 是希望它让网站所有者更好地了解其不断变化的网站指标，并作为出现问题时的诊断工具。如果您使用的是新 API，欢迎在 Chrome UX Report（讨论）Google 群组中提供反馈。
致谢
主打图片：Unsplash 上的 Dave Herring