Data publikacji: 7 lutego 2023 r., ostatnia aktualizacja: 11 kwietnia 2025 r.
Ten przewodnik przedstawia interfejs Chrome UX Report (CrUX) History API, który udostępnia serię czasową danych o wydajności witryn. Dane te są aktualizowane co tydzień i pozwalają zobaczyć historię obejmującą około 6 miesięcy z 40 punktami danych rozmieszczonymi co tydzień.
Dzięki codziennym aktualizacjom z pierwotnego punktu końcowego interfejsu CrUX API możesz teraz szybko sprawdzać najnowsze dane i informacje o tym, co działo się wcześniej. Dzięki temu możesz dokładnie obserwować zmiany w witrynie na przestrzeni czasu.
Wypróbuj interfejs API na tej stronie
Wysyłanie zapytań do dziennego interfejsu CrUX API
Przypominamy, że w poprzednim artykule na temat interfejsu CrUX API można w ten sposób uzyskać migawkę danych polowych dla konkretnego źródła:
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 }
}
}
}
Ten przegląd zawiera wartości gęstości histogramu i wartości percentylowe za określony 28-dniowy okres zbierania danych, w tym przypadku od 27 grudnia 2022 r. do 23 stycznia 2023 r.
Wysyłanie zapytania do interfejsu CrUX History API
Aby wywołać punkt końcowy historii, w poleceniu curl zmień queryRecord na queryHistoryRecord w adresie URL. Użyj tego samego klucza interfejsu API Crux, którego użyto w poprzednim wywołaniu.
collectionPeriodCount określa liczbę wpisów ciągów czasowych do zwrócenia; maksymalna wartość to 40. Jeśli nie podasz żadnej wartości, domyślnie zostanie użyta wartość 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}'
Ogólny kształt odpowiedzi jest podobny, ale zawiera znacznie więcej danych. Zamiast pojedynczego punktu danych są teraz dostępne ciągi czasowe pól zawierających 75. percentyl (p75) i wartości gęstości histogramu.
{
"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 }
}
]
}
}
W tym przykładzie seria densities dla zakresu 0–2500 ms wskaźnika największego wyrenderowania treści (LCP) wynosi [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Każda z tych gęstości została zaobserwowana podczas odpowiadającego wpisu collectionPeriods. Na przykład piąta gęstość, 0,9183, była gęstością w piątym okresie zbierania danych, który zakończył się 3 września 2022 r., a 0,9187 była gęstością w okresie, który zakończył się tydzień później.
Inaczej mówiąc, na podstawie interpretacji ostatnich wpisów w serii czasowej w przykładzie dotyczącym witryny https://web.dev stwierdzono, że od 14 sierpnia 2022 r. do 10 września 2022 r. 91, 87% wczytanych stron miało wartości LCP mniejsze niż 2500 ms, 5, 27% wartości między 2500 a 4000 ms, a 2, 85% wartości większe niż 4000 ms.
Podobnie jest w przypadku serii czasowych wartości p75: w okresie od 14 sierpnia do 10 września 2022 r. mediana LCP wynosiła 1377. Oznacza to, że w tym okresie w 75% przypadków czas LCP był krótszy niż 1377 ms, a w 25% przypadków dłuższy niż 1377 ms.
Przykład zawiera tylko 6 rekordów i okresów zbierania danych, ale odpowiedzi z interfejsu API zawierają domyślnie 25 rekordów ciągu czasowego i maksymalnie 40 rekordów, jeśli w żądaniu jest podany parametr "collectionPeriodCount": 40. Ponieważ daty zakończenia każdego z tych okresów zbierania danych przypadają w sobotę, co 7 dni, "collectionPeriodCount": 40 obejmuje 10 miesięcy.
W każdej odpowiedzi długość szeregu czasowego dla gęstości przedziałów histogramu i wartości p75 będzie dokładnie taka sama jak długość tablicy w polu collectionPeriods: istnieje jednoznaczne powiązanie na podstawie indeksu tych tablic.
Wykonywanie zapytań dotyczących danych na poziomie strony
Oprócz danych na poziomie pochodzenia interfejs CrUX History API umożliwia też dostęp do historycznych danych na poziomie strony. Dane na poziomie pochodzenia były wcześniej dostępne w zbiorze danych CrUX w BigQuery (lub za pomocą panelu CrUX), ale dane historyczne na poziomie strony były dostępne tylko wtedy, gdy strony same je zbierały i przechowywały. Nowy interfejs API umożliwia teraz dostęp do historycznych danych na poziomie strony.
Dane na poziomie strony można wyszukiwać w taki sam sposób, ale z użyciem w pliku danych wartości url zamiast 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/"}'
Dane historyczne na poziomie strony (i na poziomie pochodzenia) podlegają tym samym wymaganiom co pozostałe dane w CrUX, dlatego strony mogą nie mieć pełnego zapisu historycznego. W takich przypadkach dane „brakujące” będą reprezentowane przez wartość "NaN" dla gęstości histogramTimeseries i wartość null dla percentilesTimeseries. Różnica polega na tym, że gęstości histogramu są zawsze liczbami, a procentyle mogą być liczbami lub ciągami znaków (CLS używa ciągów znaków, nawet jeśli wyglądają jak liczby).
Wizualizacja danych
Najprostszym sposobem wizualizacji danych jest CrUX Vis, narzędzie stworzone specjalnie do demonstrowania możliwości interfejsu CrUX History API. Więcej informacji znajdziesz w dokumentacji dotyczącej wizualizacji danych w CrUX.
Aby samodzielnie generować podobne wykresy, możesz skorzystać z przykładowego pliku Colab. Colab, czyli „Colaboratory”, umożliwia pisanie i wykonywanie kodu Python bezpośrednio w przeglądarce. Colab interfejsu Crux History API (źródło) używa Pythona do wywoływania interfejsu API i tworzenia wykresów danych.
Ten dokument Colab umożliwia tworzenie wykresów p75 i wykresów trójkątnych, uzyskiwanie danych w formie tabelarycznej oraz wyświetlanie pary żądania i odpowiedzi dla interfejsu CrUX API po wypełnieniu krótkiego formularza. Aby z niego korzystać, nie musisz być programistą, ale możesz zapoznać się z kodem Pythona i zmodyfikować go, aby uzyskać niesamowite efekty. Życzymy przyjemnego korzystania i zapraszamy do dzielenia się opiniami na temat znalezionych informacji.
Oczywiście nie musisz ograniczać się do Colab ani Pythona. To tylko jeden z dostępnych przykładów korzystania z nowego interfejsu API. Jako punkt końcowy HTTP oparty na JSON interfejs API jest dostępny z jakiejkolwiek technologii.
Podsumowanie
Zanim wprowadziliśmy punkt końcowy interfejsu CrUX History API, właściciele witryn mieli ograniczony dostęp do informacji historycznych z raportu CrUX. Dane miesięczne na poziomie pochodzenia były dostępne za pomocą BigQuery i panelu CrUX, ale nie były dostępne dane tygodniowe ani dane historyczne na poziomie strony. Właściciele witryn mogli samodzielnie rejestrować te dane za pomocą interfejsu dziennego API, ale często potrzeba ich występowania była odkryta dopiero po regresji danych.
Mamy nadzieję, że wprowadzenie tego interfejsu CrUX History API pozwoli właścicielom witryn lepiej zrozumieć zmieniające się dane o witrynie i będzie służyć jako narzędzie diagnostyczne w przypadku problemów. Jeśli używasz nowego interfejsu API, możesz przesłać opinię w grupie Chrome UX Report (Discussions) w Google Groups.
Podziękowania
Baner powitalny autorstwa Dave Herring na Unsplash