發布日期：2023 年 2 月 7 日，上次更新時間：2025 年 4 月 11 日
本指南將介紹 Chrome 使用者體驗報告 (CrUX) 記錄 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 歷史記錄 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 }
}
]
}
}
在這個範例中，最大內容繪製 (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 歷史記錄 API 存取網頁層級的歷來資料。雖然先前可透過 BigQuery 上的 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/"}'
網頁層級 (和來源層級) 歷來資料須符合與其他 Chrome 使用者體驗報告資料相同的資格規定，因此特定網頁可能沒有完整的歷來記錄。在這些情況下，「遺失」的資料會以 "NaN" 表示 histogramTimeseries 密度，並以 null 表示 percentilesTimeseries。造成差異的原因是直方圖密度一律為數字，而百分位數可以是數字或字串 (即使 CLS 使用的字串看起來像數字)。
以視覺化方式呈現資料
如要輕鬆將資料視覺化，可以使用 CrUX Vis。這項工具專門用來展示 CrUX 歷史記錄 API 的強大功能。詳情請參閱 CrUX Vis 說明文件。
如要自行生成類似圖表，我們已建立 Colab 範例。Colab (全名為「Colaboratory」) 可讓你在瀏覽器中編寫及執行 Python 程式碼。CrUX 歷史記錄 API Colab (來源) 會使用 Python 呼叫 API 並繪製資料圖表。
只要填寫簡短表單，即可使用這個 Colab 製作 p75 圖表、三格圖表，以表格形式取得資料，並查看 CrUX API 的要求和回應配對。您不需要是程式設計師也能使用這項功能，但當然可以查看 Python 程式碼，並修改成令人驚豔的內容！歡迎盡情使用，並隨時提供意見回饋！
當然，您不一定要使用 Colab 或 Python，這只是使用這項新 API 的其中一個範例。這個 API 是以 JSON 為基礎的 HTTP 端點，因此可透過任何技術查詢。
結論
在 CrUX 歷史記錄 API 端點推出前，網站擁有者可從 CrUX 取得的歷史資訊有限。您可以使用 BigQuery 取得每月來源層級資料，但無法取得每週資料，也無法取得網頁層級的歷來資料。網站擁有者可以使用每日 API 記錄這項資料，但通常是在指標回歸後才發現需要這項資料。
我們希望透過推出這項 CrUX 記錄 API，協助網站擁有者更瞭解網站指標的變化，並在發生問題時做為診斷工具。如果您使用新版 API，歡迎前往 Chrome UX Report (Discussions) Google 群組提供意見。
特別銘謝
主頁橫幅圖片：Dave Herring (Unsplash)