本指南介紹了 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 }
}
]
}
}
在本範例中，最大內容繪製 (LCP) 指標中 0 到 2500 ms 值區的 densities 時間序列為 [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].，這些密度都是在對應的 collectionPeriods 項目中觀察到的。舉例來說，第 5 個密度 (0.9183) 的密度是第五個集合，到 2022 年 9 月 3 日，而 0.9187 則是結束當週結束的期間密度。
換句話說，假設分析 https://web.dev 範例中的最後時間序列項目時，發現從 2022 年 8 月 14 日到 2022 年 9 月 10 日這段期間，網頁載入中有 91.87% 的 LCP 值小於 2500 毫秒，5.27% 的值介於 2500 毫秒，5.27% 的值則介於 2500 毫秒 4028 毫秒 5.27% 之間。
同樣地，p75 值也有時間序列，2022 年 8 月 14 日的 LCP p75 直到 2022 年 9 月 10 日為 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 指標特定範圍的百分比，並以堆疊長條圖顯示。第 75 個圖表提供了簡要的總覽，在單一圖表中，您可以新增多個指標，或同時顯示 PHONE 和 DESKTOP 的線條。透過 Tri-bin 圖表，您可以瞭解各收集期間所測量指標值的分佈情形。
舉例來說，雖然第 75 版的圖表表明 https://web.dev 在觀察期間幾乎可接受的 INP 值，但 tri-bin 圖表顯示，只要載入網頁的一小部分，INP 其實不佳。兩個圖表比較容易推論有效能迴歸現象，開始於 10 月底，並在 11 月中旬前修正。
為了自行產生這類圖表，我們建立了 Colab 範例。Colab (或稱 Colaboratory) 可讓你在瀏覽器中編寫和執行 Python。CrUX History API Colab (來源) 會使用 Python 呼叫 API 並製作資料圖表。
在這個 Colab 中，你可以填寫一份簡短的表單，製作 75 個圖表、三元圖表、以表格形式取得資料，以及查看 CrUX API 的要求和回應組合。即使您不是程式設計師，也能使用這個 API，但還是可以查看 Python 程式碼，將其修改成令人驚豔的內容！希望您對於發現的資訊有任何意見，歡迎和我們分享！
當然，您不一定要使用 Colab 或 Python，而且這個新 API 只是其中一種使用範例。HTTP 端點以 JSON 為基礎，可透過任何技術查詢 API。
結論
在 CrUX History API 端點推出前，網站擁有者只能從 CrUX 取得的歷史記錄資訊有限。您可透過 BigQuery 和 CrUX 資訊主頁取得每月來源層級資料，但無法取得每週資料，也未提供網頁層級的歷來資料。網站擁有者可以使用每日 API 記錄這類資料，但通常只有在指標迴歸之後才會發現。
希望這個 CrUX History API 可讓網站擁有者進一步瞭解自己變更的網站指標，並能用來診斷發生問題的時間。如果你使用的是新的 API，歡迎透過 Chrome 使用者體驗報告 (討論) Google 群組提供意見。
特別銘謝
主頁橫幅由 Dave Herring 於 Unsplash 網站上提供