本指南介绍了 Chrome 用户体验报告 (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% 的值大于 0% 至 4000 毫秒，值为 0% 至 40.8 毫秒。
同样，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 时序的 p75 值，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 信息中心获取每月源站级数据，但无法获得每周数据，也无法获取网页级历史数据。网站所有者可以使用每日 API 自行记录这些数据，但通常情况下，只有在指标下降后，才会发现这种需求。
推出此 CrUX History API 后，我们希望它能让网站所有者更好地了解不断变化的网站指标，并在出现问题时用作诊断工具。如果您使用的是新版 API，欢迎通过 Chrome 用户体验报告（讨论）Google 网上论坛提供反馈。
致谢
主打图片：Dave Herring on Unsplash 网站