Interfejs CrUX History API zapewnia dostęp z krótkim opóźnieniem do 6-miesięcznych historycznych danych o wrażeniach użytkowników na stronie i w źródle.
Typowy przypadek użycia
Interfejs CrUX History API umożliwia wysyłanie zapytań o historyczne dane dotyczące wrażeń użytkowników w przypadku określonego identyfikatora URI, np. „Pobierz historyczne trendy UX dla źródła https://example.com
”.
Interfejs History API ma taką samą strukturę jak codzienny interfejs CrUX API, z tym że wartości są podane w tablicy, a klucze są oznaczone nazwami w liczbie mnogiej (np. histogramTimeseries
zamiast histogram
lub p75s
zamiast p75
).
Klucz interfejsu API CrUX
Podobnie jak w przypadku codziennego interfejsu API, korzystanie z interfejsu CrUX History API wymaga klucza interfejsu Google Cloud API udostępnionego do korzystania z Chrome UX Report API
. Tego samego klucza można użyć w interfejsach API Daily i History.
Uzyskiwanie i używanie klucza interfejsu API
Kup kluczMożesz też utworzyć je na stronie Dane logowania.
Gdy uzyskasz klucz interfejsu API, aplikacja może dołączać parametr zapytania
key=yourAPIKey
do wszystkich adresów URL żądań.
Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.
Zobacz przykładowe zapytania.
Model danych
W tej sekcji znajdziesz szczegółowe informacje o strukturze danych w żądaniach i odpowiedziach.
Rekord
Oddzielna informacja o stronie lub witrynie. Rekord może zawierać dane, które są charakterystyczne dla danego identyfikatora i konkretnej kombinacji wymiarów. Rekord może zawierać informacje dotyczące jednego lub większej liczby wskaźników.
Identyfikatory
Identyfikatory określają, jakie rekordy należy wyszukać. W raporcie CrUX te identyfikatory to strony internetowe i witryny.
Punkt początkowy
Gdy identyfikator jest źródłem, wszystkie dane ze wszystkich stron w tym źródle są agregowane razem. Załóżmy na przykład, że w źródle http://www.example.com
były strony określone w tej mapie witryny:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Oznacza to, że w wyniku wysłania zapytania do raportu na temat użytkowania Chrome z źródłem ustawionym na http://www.example.com
zostaną zwrócone dane dotyczące witryn http://www.example.com/
, http://www.example.com/foo.html
i http://www.example.com/bar.html
, które zostaną zagregowane, ponieważ to są wszystkie strony z tego źródła.
Adresy URL
Gdy identyfikatorem jest adres URL, zwracane są tylko dane dotyczące tego konkretnego adresu URL. Szukam mapy witryny źródłowej http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Jeśli identyfikator jest ustawiony na adres URL o wartości http://www.example.com/foo.html
, zwracane są tylko dane dotyczące tej strony.
Wymiary
Wymiary określają konkretną grupę danych, względem których rekord jest agregowany. Na przykład format PHONE
oznacza, że rekord zawiera informacje o wczytaniach, które miały miejsce na urządzeniu mobilnym.
Interfejs CrUX History API jest dostępny tylko agregowana według wymiaru formatu. To ogólna klasa urządzeń podzielona na PHONE
, TABLET
i DESKTOP
.
Dane
Dane są podawane w postaci ciągów czasowych zagregowanych danych statystycznych, takich jak histogramy, percentyle, i ułamki.
Histogramy
Gdy wskaźniki są wyrażone w tablicy histogramu, każdy wpis ciągu czasowego reprezentuje procent wczytywania strony, w przypadku których dane znalazły się w odcinku proporcjonalnie do wszystkich. Punkty danych są wyświetlane według dat okresu gromadzenia danych zwracanych również przez interfejs API, przy czym pierwszy punkt to najwcześniejszy okres, a ostatni punkt – ostatni okres zbierania danych.
Histogram trzech przedziałów dla przykładowych danych wygląda tak:
{
"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]
}
],
}
Te dane wskazują, że w przypadku 91,90% wczytań stron przykładowa wartość danych wynosiła od 0 do 2500 ms na pierwszy okres zbierania danych w historii, a następnie w 92,03%, 91,94%... Ten histogram nie zawiera jednostek danych, w tym przypadku przyjmujemy milisekundy.
Dodatkowo w przypadku 5,21% wczytań stron przykładowa wartość danych wynosiła od 2500 do 4000 ms w pierwszym okresie zbierania danych w historii, a w przypadku 2,88% wczytań stron wartość w pierwszym okresie zbierania danych w historii wynosiła ponad 4000 ms.
Centyl
Wskaźniki mogą też zawierać ciągi czasowe centyli, które mogą być przydatne przy dodatkowej analizie.
Punkty danych są wyświetlane według dat okresu gromadzenia danych zwracanych również przez interfejs API, przy czym pierwszy punkt to najwcześniejszy okres, a ostatni punkt – ostatni okres zbierania danych.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Te percentyle mogą pokazywać konkretne wartości danych w danym percentylu. Są one oparte na pełnym zbiorze dostępnych danych, a nie na ostatecznych danych powiązanych, więc nie muszą być zgodne z interpolowanym percentylem opartym na końcowym histogramie binarnym.
Ułamki
Dane mogą być wyrażone jako ciągi czasowe ułamków oznaczonych etykietami. każda etykieta opisuje wczytanie strony w określonym sposób. Punkty danych są wyświetlane według dat okresu gromadzenia danych zwracanych również przez interfejs API, przy czym pierwszy punkt to najwcześniejszy okres, a ostatni punkt – ostatni okres zbierania danych.
Przykład:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
W tym przykładzie najnowszy punkt danych wskazuje, że 14,21% wczytań stron pochodziło z komputerów i 82,88% z telefonów.
Typy wartości danych
Interfejs CrUX History API używa tych samych typów wartości danych, dlatego więcej informacji znajdziesz w codziennej dokumentacji dotyczącej typów wartości wskaźników w interfejsie CrUX.
Wymagania dotyczące danych
W zależności od kryteriów kwalifikacji źródło lub adres URL mogą kwalifikować się do zbierania danych tylko w niektórych okresach uwzględnianych w interfejsie CrUX History API. W takich przypadkach interfejs CrUX History API zwróci wartość "NaN"
w przypadku gęstości histogramTimeseries
i null
dla percentilesTimeseries
dla okresów zbierania danych, które nie mają odpowiednich danych. Przyczyną tej różnicy jest to, że gęstości histogramu zawsze są liczbami, a percentylami mogą być liczbami lub ciągami znaków (w CLS używane są ciągi tekstowe, nawet jeśli wyglądają jak liczby).
Jeśli np. w drugim okresie nie było żadnych odpowiednich danych, będzie on wyglądał tak:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
W przypadku adresów URL lub źródeł, które z czasem zaczną się kwalifikować lub nie będą kwalifikować się do wyświetlania, możesz zauważyć wiele brakujących pozycji.
Okresy zbierania danych
Interfejs CrUX History API zawiera obiekt collectionPeriods
z tablicami z polami firstDate
i endDate
reprezentującymi daty rozpoczęcia i zakończenia każdego okna agregacji. Na przykład:
"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 }
}
]
Te okresy zbierania są uporządkowane rosnąco i odpowiadają zakresowi dat dla każdego punktu danych w innych sekcjach odpowiedzi.
Interfejs History API jest aktualizowany w każdy poniedziałek i zawiera dane aż do poprzedniej soboty (zgodnie ze standardowym dwudniowym opóźnieniem). Zawiera on dane z ostatnich 25 tygodni – 1 okres zbierania na tydzień.
Każdy okres zbierania danych zawiera zbiorcze dane z poprzednich 28 dni, a okresy zbierania danych są podzielone na tygodnie, co oznacza, że te okresy będą się pokrywać. Są one podobne do średniej kroczącej danych – w każdym kolejnym okresie uwzględniane są dane z 3 tygodni, a z jednego tygodnia są różne.
Przykładowe zapytania
Zapytania są przesyłane jako obiekty JSON za pomocą żądania POST do https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]"
z danymi zapytań jako obiektem JSON w treści POST.
Zwróć uwagę na użycie funkcji queryHistoryRecord
zamiast queryRecord
w codziennym interfejsie CrUX API.
Przykładowy tekst:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Można je na przykład wywołać z curl
przy użyciu tego wiersza poleceń (zastępując API_KEY
swoim kluczem):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
Dane na poziomie strony są dostępne w interfejsie API poprzez przekazanie w zapytaniu właściwości url
zamiast origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Jeśli właściwość metrics
nie jest skonfigurowana, zwracane są wszystkie dostępne dane:
cumulative_layout_shift
first_contentful_paint
first_input_delay
interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
round_trip_time
form_factors
(raportowany tylko wtedy, gdy w żądaniu nie określono żadnego elementuformFactor
)
Jeśli nie podasz żadnej wartości formFactor
, wartości zostaną zagregowane dla wszystkich formatów.
Więcej przykładowych zapytań znajdziesz w artykule Korzystanie z interfejsu CrUX History API.
Potok danych
Zbiór danych CrUX jest przetwarzany za pomocą potoku w celu konsolidowania, agregowania i filtrowania danych przed ich udostępnieniem przez interfejs API.
Średnia krocząca
Dane w Raporcie na temat użytkowania Chrome to średnia krocząca z 28 dni. Oznacza to, że dane przedstawiane w Raporcie na temat użytkowania Chrome w danym momencie są sumowanymi danymi z ostatnich 28 dni.
Interfejs History API obejmuje kilka okresów zbierania danych, z których każdy obejmuje te 28 dni. Każdy okres zbierania danych zawiera zbiorcze dane z poprzednich 28 dni, a okresy zbierania danych są podzielone na tygodnie, co oznacza, że te okresy będą się pokrywać. Są one podobne do średniej kroczącej danych – w każdym kolejnym okresie uwzględniane są dane z 3 tygodni, a z jednego tygodnia są różne.
Cotygodniowe aktualizacje
Interfejs History API jest aktualizowany w każdy poniedziałek około godziny 04:00 czasu UTC i zawiera dane aż do poprzedniej soboty (zgodnie ze standardowym dwudniowym opóźnieniem). Zawiera on dane z ostatnich 25 tygodni (około 6 miesięcy) – 1 okres gromadzenia w tygodniu.
Nie ma gwarancji jakości usług dla czasu aktualizacji. jest codziennie przeprowadzany z możliwie największą dokładnością.
Schemat
Interfejs CrUX History API ma jeden punkt końcowy, który akceptuje żądania HTTP POST
. Interfejs API zwraca wartość record
, która zawiera co najmniej 1 element metrics
odpowiadający danym o wydajności żądanego źródła lub strony.
Żądanie HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord
Adres URL używa składni transkodowania gRPC.
Treść żądania
Interfejs CrUX History API korzysta z tych samych treści żądań co codzienny interfejs API CrUX, z wyjątkiem pola, które nie obsługuje pola effectiveConnectionType
.
Aby na przykład zażądać wartości największego wyrenderowania treści na komputery dla strony głównej web.dev:
{
"origin": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Treść odpowiedzi
Żądania zakończone powodzeniem zwracają odpowiedzi z obiektem record
i obiektem urlNormalizationDetails
o następującej strukturze:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Odpowiedź na treść poprzedniego żądania może na przykład wyglądać tak:
{
"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 }
}, {
...
}
]
}
}
Klucz
Key
określa wszystkie wymiary, które identyfikują ten rekord jako unikalny.
{
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Pola | |
---|---|
formFactor |
Format to klasa urządzenia, której wszyscy użytkownicy użyli, aby uzyskać dostęp do witryny z tym rekordem. Jeśli format nie jest określony, zostaną zwrócone dane zbiorcze ze wszystkich formatów. |
Pole sumy url_ . Wzorzec adresu URL to adres URL, do którego odnosi się rekord. url_ może mieć tylko jedną z tych wartości: |
|
origin |
Origin określa źródło, dla którego jest przeznaczony ten rekord. Uwaga: przy określaniu punktu początkowego dane dotyczące wczytywania w ramach tego punktu początkowego na wszystkich stronach są agregowane w ramach danych dotyczących wrażeń użytkowników na poziomie źródła. |
url |
Uwaga: w przypadku parametru |
Dane
metric
to zbiór danych o wrażeniach użytkownika związanych z pojedynczym rodzajem danych dotyczących wydajności witryny, np. pierwsze wyrenderowanie treści. Zawiera on histogram podsumowania rzeczywistego użytkowania Chrome w formie serii bins
.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
lub
"fractionTimeseries": {
object (Fractions)
}
Pola | |
---|---|
histogramTimeseries[] |
Histogram ciągów czasowych przedstawiający wrażenia użytkownika w przypadku danego wskaźnika. Histogram ciągu czasowego będzie miał co najmniej jeden przedział, a gęstość wszystkich przedziałów będzie równa ok. 1. Brakujące wartości w danym okresie zbierania danych zostaną oznaczone jako |
percentilesTimeseries |
Typowe przydatne centyle wskaźnika. Typ wartości percentyli będzie taki sam jak typy wartości podane dla przedziałów histogramu. Brakujące wartości w danym okresie zbierania danych zostaną oznaczone jako |
fractionTimeseries |
Ten obiekt zawiera ciągi czasowe ułamków oznaczonych etykietami, które dają łącznie około 1 na wpis. Ułamki są zaokrąglane do 4 miejsc po przecinku. Brakujące wpisy są wyrażone jako „NaN” dla wszystkich ułamków. |
Przedział
Pole bin
to odrębny fragment danych rozciągających się od początku do końca lub jeśli nie ma podanego końca od początku do dodatniej nieskończoności.
Początek i koniec przedziału są podane w typie wartości reprezentowanego przez niego wskaźnika. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczby całkowite, dlatego jego przedziały wskaźników będą używały int32 jako typów rozpoczęcia i zakończenia. Skumulowane przesunięcie układu jest jednak mierzone w bezjednostkowych ułamkach dziesiętnych i przedstawia je jako ciąg znaków zakodowany w postaci dziesiętnej, dlatego jego typy danych będą zawierać ciągi tekstowe.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
Pola | |
---|---|
start |
Początek to początek przedziału danych. |
end |
Argument koniec wskazuje koniec przedziału danych. Jeśli pole end nie jest wypełnione, przedział nie ma końca i jest prawidłowy od początku do +inf. |
densities |
Ciągi czasowe odsetka użytkowników, u których wystąpiła wartość przedziału w przypadku danego rodzaju danych. Gęstości są zaokrąglane do 4 miejsc po przecinku. |
Centyl
Percentiles
zawiera syntetyczne wartości danych dla danego centyla statystycznego. Służą do szacowania wartości danych w odniesieniu do odsetka użytkowników w stosunku do łącznej liczby użytkowników.
{
"P75": value
}
Pola | |
---|---|
p75s |
Ciągi czasowe wartości, w przypadku których 75% wczytań strony napotkały dany rodzaj danych, nie przekraczały tej wartości. |
Ułamki
Fractions
zawiera ciągi czasowe oznaczonych ułamkami, które sumują się do około 1 na wpis.
Każda etykieta opisuje w jakiś sposób wczytanie strony, więc dane są przedstawiane w ten sposób.
można traktować jako źródło odrębnych wartości, a nie liczbowych,
ułamki wskazują, jak często mierzona była dana różna wartość.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Podobnie jak wartości gęstości w przedziałach histogramu, każdy element fraction
jest liczbą
0.0 <= value <= 1.0
i dają łącznie ok.1, 0. Gdy dane są niedostępne
dla danego okresu zbierania danych, odpowiednia pozycja zostanie
„NaN” we wszystkich tablicach ułamków.
Pola | |
---|---|
p75s |
Ciągi czasowe wartości, w przypadku których 75% wczytywanych stron wystąpiły, miały określone dane z wartością nie większą niż ta. |
UrlNormalization
Obiekt reprezentujący działania normalizacji wykonane w celu normalizacji adresu URL w celu zwiększenia szansy na pomyślne wyszukiwanie. To proste automatyczne zmiany wprowadzane podczas wyszukiwania podanego elementu url_pattern
, który zwykle kończy się niepowodzeniem. Złożone działania, takie jak śledzenie przekierowań, nie są obsługiwane.
{
"originalUrl": string,
"normalizedUrl": string
}
Pola | |
---|---|
originalUrl |
Pierwotny żądany adres URL przed działaniami normalizacji. |
normalizedUrl |
Adres URL po wszystkich działaniach normalizacji. Jest to prawidłowy adres URL związany z wrażeniami użytkownika, który można łatwo wyszukać. |
Ograniczenia liczby żądań
Interfejs CrUX History API ma taki sam limit jak CrUX API. W przypadku każdego projektu Google Cloud można wysłać 150 zapytań na minutę na minutę dla każdego z tych interfejsów API (to rozwiązanie jest oferowane bezpłatnie). Ten limit oraz informacje o bieżącym wykorzystaniu znajdziesz w Google Cloud Console. Ten wysoki limit powinien być wystarczający w większości przypadków użycia. Nie ma możliwości płacenia za zwiększenie limitu.