本指南將介紹 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 }
}
}
}
這份數據匯報包含 2022 年 12 月 27 日至 2023 年 1 月 23 日這段期間的直方圖密度值，以及特定 28 天收集期間的直方圖密度值。
查詢 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 ms 值區的 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%0 毫秒至 4008 毫秒，
同樣地，p75 值也有時間序列，2022 年 8 月 14 日到 2022 年 9 月 10 日的 LCP p75 為 1377。這代表在資料收集期間，75% 的使用者體驗 LCP 低於 1377 毫秒，25% 的使用者體驗的 LCP 則大於 1377 毫秒。
這個範例只列出 6 個時間序列項目和集合期間，但來自 API 的回應則會提供 25 個時間序列項目。由於每個收集期間的結束日期均為 7 天相隔 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 的「與下一個繪製內容互動 (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 可讓你填寫第 75 個圖表、三元圖表、以表格形式取得資料，並透過填寫簡短的表單查看 CrUX API 的要求與回應組合。即使您不是程式設計人員，也可以使用 Python 程式碼，但其實只要查看 Python 程式碼，再化為傑出效果即可！希望您喜歡這個功能，也歡迎您隨時針對您所發現的內容提供意見回饋！
當然，你不一定要侷限於 Colab 或 Python，這只是如何使用這個新 API 的範例。做為 JSON 型的 HTTP 端點，可透過任何技術查詢。
結論
在 CrUX History API 端點推出前，網站擁有者對於從 CrUX 可取得的歷來資料都有限。透過 BigQuery 和 CrUX 資訊主頁，可取得每月來源層級資料，但無法取得每週資料或網頁層級的歷來資料。網站擁有者可以使用每日 API 自行記錄這些資料，但通常只有在指標降低後才發現需要這些資料的情況。
隨著這個 CrUX History API 的推出，我們希望能讓網站擁有者更加瞭解不斷變化的網站指標，並在發生問題時使用診斷工具。如果您使用的是新版 API，歡迎透過 Chrome 使用者體驗報告 (討論) Google 群組提供意見。
特別銘謝
主頁橫幅由 Dave Herring 於 Unsplash 提供