Interfejs API CrUX

Interfejs CrUX API zapewnia szybki dostęp do zbiorczych danych o użytkownikach na poziomie strony i źródła.

Wypróbuj

Typowy przypadek użycia

Interfejs CrUX API umożliwia wysyłanie zapytań o dane o ocenie funkcjonalności dotyczące konkretnego adresu URI, np. „Pobierz dane o źródle https://example.com”.

Klucz interfejsu API CrUX

Korzystanie z interfejsu API CrUX wymaga klucza interfejsu Google Cloud API udostępnionego do użycia w ramach Chrome UX Report API.

Uzyskiwanie i używanie klucza interfejsu API

Możesz też utworzyć konto na stronie Dane logowania.

Gdy uzyskasz klucz interfejsu API, Twoja aplikacja będzie mogła dołączać parametry zapytania key=yourAPIKey do adresów URL wszystkich żą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.

Nagraj

Pojedyncza informacja o stronie lub witrynie. Rekord może zawierać dane dotyczące konkretnego identyfikatora i konkretnej kombinacji wymiarów. Rekord może zawierać dane dotyczące co najmniej 1 rodzaju danych.

Identyfikatory

Identyfikatory określają, jakie rekordy mają być wyszukiwane. W przypadku CrUX są to strony internetowe i witryny.

Punkt początkowy

Jeśli identyfikator to źródło, wszystkie dane na wszystkich stronach w tym źródle są agregowane. Załóżmy na przykład, że domen http://www.example.com dotyczyły strony o takim układzie w tej mapie witryny:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Oznacza to, że po przesłaniu zapytania do raportu na temat użytkowania Chrome z ustawionym źródłem http://www.example.com zwrócone zostaną dane o witrynach http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, które zostaną zgrupowane, ponieważ wszystkie te strony należą do tego źródła.

Adresy URL

Jeśli identyfikator to adres URL, zwrócone zostaną tylko dane dotyczące tego konkretnego adresu. Ponownie patrz na mapę witryny http://www.example.com źródłową:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Jeśli identyfikator ma wartość http://www.example.com/foo.html, zwracane są tylko dane o tej stronie.

Wymiary

Wymiary identyfikują konkretną grupę danych, na podstawie której rekord jest agregowany. Na przykład format PHONE wskazuje, że rekord zawiera informacje o wczytywaniu, które miało miejsce na urządzeniu mobilnym. Każdy wymiar ma określoną liczbę wartości, a brak jego określenia oznacza, że jest on agregowany według wszystkich wartości. Na przykład brak formatu wskazuje, że rekord zawiera informacje o załadowaniach, które miały miejsce w dowolnym formacie.

Format

Klasa urządzenia, którego użytkownik użył do przejścia na stronę. To ogólna klasa urządzeń podzielona na PHONE, TABLET i DESKTOP.

Dane

Dane podajemy w formie agregacji statystycznych, histogramów, wartości procentowych i ułamków.

Wartości zmiennoprzecinkowe są zaokrąglane do 4 miejsc po przecinku (pamiętaj, że dane cumulative_layout_shift to podwójne liczby zmiennoprzecinkowe zakodowane jako ciąg znaków, więc nie są one uważane za liczby zmiennoprzecinkowe i są raportowane z dokładnością do 2 miejsc po przecinku w ciągu znaków).

Histogram

Gdy dane są wyrażone w histogramie, pokazujemy odsetki wczytań stron, które mieszczą się w określonych zakresach.

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

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Te dane wskazują, że w przypadku 38,18% wczytań strony przykładowe dane zostały zmierzone w zakresie od 0 ms do 1000 ms. Jednostki danych nie są zawarte w tym histogramie. W tym przypadku przyjmujemy, że są to milisekundy.

Dodatkowo w 49,91% przypadków wartość danych w przypadku wczytywania strony mieściła się w zakresie od 1000 ms do 3000 ms, a w 11,92% przypadków była większa niż 3000 ms.

Percentyle

Dane mogą też zawierać wartości procentowe, które mogą być przydatne do dodatkowych analiz. Raportujemy konkretne wartości danych dla danego przedziału dziesiętnego. Są one oparte na pełnym zbiorze dostępnych danych, a nie na ostatecznych danych zgrupowanych, dlatego nie muszą być zgodne z interpolowaną wartością Percentyla, która jest oparta na ostatecznym histogramie zgrupowanych danych.

{
  "percentiles": {
    "p75": 2063
  }
}

W tym przykładzie co najmniej 75% wczytań strony zostało zmierzone za pomocą wartości danych <= 2063.

Ułamki

Ułamki wskazują odsetki wczytywania stron, które można oznaczyć w określony sposób. W tym przypadku wartościami danych są te etykiety.

Na przykład dane form_factors składają się z obiektu fractions, który zawiera podział na formaty (lub urządzenia), które obejmuje dane zapytanie:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

W tym przypadku zmierzono 3,77% wczytań strony na komputerze, 2,88% na tablecie i 93,35% na telefonie, co daje w sumie 100%.

Typy wartości danych

Mapowanie nazwy typu danych BigQuery

Okres zbierania danych

Od października 2022 r. interfejs CrUX API zawiera obiekt collectionPeriod z polami firstDate i endDate, które reprezentują daty rozpoczęcia i zakończenia okna agregacji. Na przykład:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Dzięki temu łatwiej zrozumieć dane i sprawdzić, czy zostały one zaktualizowane w tym dniu, czy zwracają te same dane co wczoraj.

Okres zbierania danych jest też dostępny w PageSpeed Insights:

Dodatkowo collectionPeriod zawsze będzie wyświetlać 28-dniowy okres, nawet jeśli dane nie obejmują pełnych 28 dni (np. jeśli strona została opublikowana mniej niż 28 dni temu). collectionPeriod to okres, w którym dane CrUX zostały zagregowane, ale niekoniecznie okres, z którego pochodzą dane.

Przykładowe zapytania

Zapytania są przesyłane jako obiekty JSON za pomocą żądania POST do adresu https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" z danymi zapytania w postaci obiektu JSON w ciele żądania POST:

{
  "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:queryRecord?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 przez interfejs API, jeśli w zapytaniu podasz usługę 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 ustawiona, 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
• form_factors (zwracane tylko wtedy, gdy w żądaniu nie jest określony parametr formFactor)

Jeśli nie podasz wartości formFactor, wartości zostaną zsumowane dla wszystkich formatów.

Więcej przykładowych zapytań znajdziesz w artykule Korzystanie z interfejsu API raportu na temat użytkowania Chrome.

Potok danych

Zbiór danych CrUX jest przetwarzany w ramach potoku, aby skonsolidować, zagregować i odfiltrować dane, zanim staną się dostępne za pomocą interfejsu API.

Średnia krocząca

Dane w raporcie na temat użytkowania Chrome to średnia krocząca z 28 dni obejmująca zagregowane dane. Oznacza to, że dane prezentowane w raporcie na temat użytkowania Chrome w danym momencie to w istocie dane z ostatnich 28 dni zebrane w jedną całość.

Jest to podobne do sposobu, w jaki zbiór danych CRUX w BigQuery agreguje raporty miesięczne.

Aktualizacje codzienne

Dane są aktualizowane codziennie około godziny 4:00 czasu UTC. Nie ma gwarancji jakości usług dotyczących czasu aktualizacji. Jest ona wykonywana codziennie w miarę możliwości.

Schemat

Interfejs CrUX API ma 1 punkt końcowy, który akceptuje POST żądania HTTP. Interfejs API zwraca record, który zawiera co najmniej 1 element metrics odpowiadający danym o skuteczności dotyczącym żądanego źródła lub strony.

Żądanie HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

Adres URL używa składni transkodowania gRPC.

Treść żądania

Treść żądania powinna zawierać dane o tej strukturze:

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // 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.
}

Aby na przykład uzyskać wartości największego wyrenderowania treści na komputerze dla strony głównej dokumentacji dla programistów Chrome:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Treść odpowiedzi

Pomyślne żądania zwracają odpowiedzi z obiektem record i urlNormalizationDetails o tej strukturze:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Odpowiedź na treść poprzedniego zapytania może wyglądać na przykład tak:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Klucz

Key definiuje wszystkie wymiary, które wskazują, że rekord jest 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.
}

Dane

metric to zestaw zagregowanych danych dotyczących wygody korzystania z pojedynczego wskaźnika wydajności strony internetowej, np. pierwszego wyrenderowania treści. Może zawierać podsumowanie histogramu rzeczywistego użytkowania Chrome w postaci serii bins, danych dotyczących konkretnych wartości percentylowych (np. p75) lub oznaczone ułamki.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

lub

{
  "fractions": {
    object (Fractions)
  }
}

Przedział

bin to dyskretna część danych obejmująca zakres od początku do końca lub, jeśli nie ma podanego końca, od początku do dodatniej nieskończoności.

Wartości początkowa i końcowa przedziału są podawane w typie wartości danych, które reprezentują. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczba całkowita, dlatego jego zakresy danych będą używać typu int32 dla typów początku i końca. Jednak skumulowane przesunięcie układu jest mierzone w bezwymiarowych liczbach dziesiętnych i wyświetlane jako liczba dziesiętna zakodowana jako ciąg znaków, dlatego jego zakresy danych będą używać ciągów znaków jako typu wartości.

{
  "start": value,
  "end": value,
  "density": number
}

Percentyle

Percentiles zawiera wartości syntetyczne danych przy danym percentylu statystycznym. Są one używane do oszacowania wartości danych jako odsetek łącznej liczby użytkowników.

{
  "P75": value
}

Ułamki

Fractions zawiera etykietowane ułamki, których suma wynosi około 1. Każda etykieta w jakiś sposób opisuje wczytanie strony, więc dane reprezentowane w ten sposób można uznać za wartości niepowtarzalne zamiast liczbowe, a ułamki wyrażają, jak często była mierzona dana niepowtarzalna wartość.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Podobnie jak wartości gęstości w przedziałach histogramu, każda wartość fraction jest liczbą 0.0 <= value <= 1.0, a ich suma wynosi około 1,0.

UrlNormalization

Obiekt reprezentujący działania normalizacyjne podjęte w celu ujednoliwienia adresu URL, aby zwiększyć szansę na znalezienie go. Są to proste, automatyczne zmiany, które są wprowadzane, gdy wiadomo, że wyszukiwanie podanych wartości url_pattern zakończy się niepowodzeniem. Złożone działania, takie jak śledzenie przekierowań, nie są obsługiwane.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Ograniczenia liczby żądań

Interfejs CrUX API jest ograniczony do 150 zapytań na minutę w przypadku każdego projektu Google Cloud, który jest oferowany bezpłatnie. Ten limit i aktualne wykorzystanie możesz sprawdzić w konsoli Google Cloud. Ten obszerny limit powinien wystarczyć w większości przypadków. Nie można płacić za zwiększenie limitu.