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.

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. Tego samego klucza można użyć w interfejsach API Daily i History.

Możesz go utworzyć na stronie Credentials (Dane logowania) i udostępnić go do korzystania z Chrome UX Report API.

Gdy uzyskasz klucz interfejsu API, Twoja aplikacja może dołączać parametr zapytania key=[YOUR_API_KEY] do wszystkich adresów URL żądań. Zobacz Przykładowe zapytania.

Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.

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.

Wskaźnik

Dane prezentujemy w postaci ciągów czasowych zagregowanych danych statystycznych, czyli histogramów, percentyli i ułamków.

Histogramy

Gdy dane są wyrażone w postaci histogramu, każdy wpis ciągu czasowego reprezentuje procent przypadków wczytania strony, w przypadku których dane zostały podzielone na przedział 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.

Prosty histogram z trzema binami dla przykładowego wskaźnika 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ć przedstawione jako ciągi czasowe ułamków oznaczonych etykietami, a każda etykieta opisuje wczytanie strony w określony 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 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 za pomocą potoku w celu konsolidacji, 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 dotyczących czasu aktualizacji. Jest ona przeprowadzana z najwyższą starannością każdego dnia.

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 CrUX API. Wyjątkiem jest brak obsługi 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ó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_pattern. Wzorzec adresu URL to adres URL, do którego odnosi się 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.

Wskaźniki

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 metryczne będą używać 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

(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, dlatego dane reprezentowane w ten sposób można traktować jako generujące różne wartości, a nie wartości liczbowe, a ułamki wskazują, jak często mierzona była dana odrębna 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 to liczba 0.0 <= value <= 1.0, a suma ich sumy wynosi ok.1,0. Jeśli wskaźnik jest niedostępny dla danego okresu zbierania danych, odpowiedni wpis ma 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.