Interfejs CrUX History API

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.

Wypróbuj

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 dzienny interfejs CrUX API, z tym wyjątkiem, że wartości są podawane w tablicy, a klucze mają nazwy w liczbie mnogiej (np. histogramTimeseries zamiast histogram lub p75s zamiast p75).

Klucz interfejsu API CrUX

Podobnie jak w przypadku interfejsu daily API, korzystanie z interfejsu CrUX History API wymaga klucza interfejsu Google Cloud API przeznaczonego do użytku w ramach Chrome UX Report API. Ten sam klucz można używać do interfejsu dziennego i historycznego.

Uzyskiwanie i używanie klucza interfejsu API

Kup klucz

Możesz też utworzyć konto 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

Ta sekcja zawiera szczegółowe informacje o strukturze danych w żądaniach i odpowiedziach.

Rekord

Pojedyncza 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 stron, 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.

Wygląd histogramu z 3 przedziałami dla przykładowych danych:

{
  "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 pierwszym okresie zbierania danych w historii 5,21% wczytanych stron miało wartość przykładowego wskaźnika między 2500 ms a 4000 ms, a 2,88% wczytanych stron miało wartość większą niż 4000 ms.

Centyl

Dane mogą też zawierać szeregi czasowe z wartościami percentylowymi, które mogą być przydatne do dodatkowych analiz.

Punkty danych są prezentowane w kolejności odpowiadającej dacie okresu gromadzenia, która jest również zwracana przez interfejs API. Pierwszy punkt odpowiada najstarszemu okresowi, a ostatni – najmłodszemu okresowi gromadzenia.

{
  "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" dla gęstości histogramTimeseries i wartość null dla percentilesTimeseries w przypadku okresów zbierania danych, w których nie ma kwalifikujących się 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 dane zagregowane z poprzednich 28 dni, a okresy zbierania danych są tygodniowe, co oznacza, że okresy zbierania danych będą się na siebie nakładać. 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 go na przykład wywołać z poziomu curl za pomocą tego wiersza poleceń (z zastąpionym kluczem API_KEY):

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
• 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 elementu formFactor)

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 w ramach potoku, aby skonsolidować, zagregować i odfiltrować dane, zanim staną się dostępne 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

History API jest aktualizowane co poniedziałek około godziny 4:00 UTC i zawiera dane do poprzedniej soboty (z standardowym 2-dniowym opóźnieniem). Zawiera 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	enum (FormFactor) Format to klasa urządzenia, którego używali wszyscy użytkownicy, aby uzyskać dostęp do witryny w przypadku tego rekordu. Jeśli format nie jest określony, zostaną zwrócone dane zbiorcze ze wszystkich formatów.
Pole sumy url_pattern. Wzorzec adresu URL to adres URL, którego dotyczy rekord. url_pattern może mieć tylko jedną z tych wartości:
origin	string 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	string url określa konkretny adres URL, którego dotyczy ten rekord. Uwaga: w przypadku parametru url zostaną zagregowane tylko dane dotyczące tego konkretnego adresu URL.

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[]	object (Bin) 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 "NaN".
percentilesTimeseries	object (Percentiles) 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 null.
fractionTimeseries	object (Fractions) 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 postaci ułamków 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	(integer | string) Początek to początek przedziału danych.
end	(integer | string) 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	array[number] 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	array[(integer | string)] 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. Jeśli dane są niedostępne w przypadku konkretnego okresu zbierania danych, odpowiedni wpis będzie miał wartość „NaN” we wszystkich tablicach ułamków.

Pola
p75s	array[(integer | string)] 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	string Pierwotny żądany adres URL przed działaniami normalizacji.
normalizedUrl	string 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.