本指南將介紹 Chrome 使用者體驗報告 (CrUX) 歷史記錄 API 端點，可提供網站效能資料的時間序列。這項資料每週更新，一次會顯示約 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
如要呼叫歷史記錄端點，請將網址中的 queryRecord 變更為 curl 指令中的 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 毫秒區塊的 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 個時間序列項目；由於每個收集期間的結束日期都是相隔 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/"}'
網頁層級 (和來源層級) 的歷來資料必須符合相同的資格條件，因此網頁可能沒有完整的歷來記錄。在這種情況下，histogramTimeseries 密度的「缺少」資料會以 "NaN" 表示，percentilesTimeseries 的「缺少」資料則會以 null 表示。之所以有差異，是因為直方圖密度一律是數字，而百分位數可以是數字或字串 (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 端點，可透過任何技術查詢。
結論
在 CrUX History API 端點推出前，網站擁有者對於從 CrUX 可取得的歷來資料都有限。透過 BigQuery 和 CrUX 資訊主頁，可取得每月來源層級資料，但無法取得每週資料或網頁層級的歷來資料。網站擁有者可以使用每日 API 自行記錄這類資料，但通常只有在指標出現回歸時，才會發現這類需求。
隨著這個 CrUX History API 的推出，我們希望能讓網站擁有者更加瞭解不斷變化的網站指標，並在問題發生時提供診斷工具。如果您使用的是新版 API，歡迎前往 Chrome UX Report (討論) Google 群組提供意見。
特別銘謝
主頁橫幅圖片由 Dave Herring 提供，取自 Unsplash