Interfejs API CrUX

Interfejs CrUX API zapewnia dostęp o niskim opóźnieniu do zagregowanych danych o wrażeniach prawdziwych użytkowników na poziomie strony i źródła.

Wypróbuj

Częsty przypadek użycia

Interfejs CrUX API umożliwia wysyłanie zapytań o dane dotyczące wygody użytkowników w przypadku konkretnego identyfikatora URI, np. „Pobierz dane dotyczące źródła https://example.com”.

Klucz interfejsu API CrUX

Korzystanie z interfejsu CrUX API wymaga klucza interfejsu Google Cloud API udostępnionego na potrzeby Chrome UX Report API.

Uzyskiwanie i używanie klucza interfejsu API

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

Gdy masz już klucz interfejsu API, Twoja 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 opisano strukturę danych w żądaniach i odpowiedziach.

Nagraj

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

Identyfikatory

Identyfikatory określają, które rekordy mają być wyszukiwane. W CrUX tymi identyfikatorami są strony internetowe i witryny.

Punkt początkowy

Jeśli identyfikatorem jest źródło, wszystkie dane dotyczące wszystkich stron w tym źródle są agregowane. Załóżmy na przykład, że źródło http://www.example.com zawiera strony rozmieszczone zgodnie z tą mapą witryny:

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

Oznacza to, że podczas wysyłania zapytania do raportu na temat użytkowania Chrome ze źródłem ustawionym na http://www.example.com zostaną zwrócone dane dla http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, które zostaną zagregowane, ponieważ wszystkie te strony znajdują się w tym źródle.

Adresy URL

Jeśli identyfikator jest adresem URL, zwracane są tylko dane dotyczące tego konkretnego adresu. Spójrzmy jeszcze raz na mapę witryny 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 URL z wartością http://www.example.com/foo.html, zwracane będą tylko dane dotyczące tej strony.

Wymiary

Wymiary identyfikują konkretną grupę danych, według 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 będzie miał określoną liczbę wartości, a brak określenia tego wymiaru będzie oznaczał, że wymiar jest agregowany we wszystkich wartościach. Na przykład brak określenia formatu oznacza, że rekord zawiera informacje o załadunkach, które miały miejsce w dowolnym formacie.

Format

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

Wskaźnik

Dane raportowania są raportowane jako agregacje statystyczne w histogramach, percentylach i ułamkach.

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

Histogram

Gdy dane są przedstawione na histogramie, pokazujemy odsetek wczytań strony, które mieszczą się w określonych zakresach dla tych danych.

Histogram z 3 przedziałami dla przykładowych danych wygląda tak:

{
  "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ładowy wskaźnik został zmierzony w zakresie od 0 ms do 1000 ms. Jednostki danych nie są zawarte w tym histogramie. W tym przypadku przyjmiemy milisekundy.

Dodatkowo w 49,91% przypadków wczytania strony wartość danych 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ć percentyle, które mogą być przydatne w dodatkowych analizach. Podajemy konkretne wartości danych w danym percentylu. Są one oparte na pełnym zestawie dostępnych danych, a nie na ostatecznych danych podzielonych na przedziały, więc nie muszą odpowiadać interpolowanemu percentylowi opartemu na ostatecznym histogramie podzielonym na przedziały.

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

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

Ułamki

Ułamki wskazują odsetek wczytań strony, 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 zestawienie formatów (lub urządzeń) objętych danym zapytaniem:

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

W tym przypadku 3,77% wczytań strony zostało zmierzonych na komputerze, 2,88% – na tablecie, a 93,35% – na telefonie, co daje łącznie 100%.

Typy wartości danych

Mapowanie nazw danych BigQuery

Okres zbierania

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 możesz lepiej zrozumieć dane i dowiedzieć się, czy zostały już zaktualizowane w danym dniu, czy też są takie same jak poprzedniego dnia.

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

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

Przykładowe zapytania

Zapytania są przesyłane jako obiekty JSON za pomocą żądania POST do https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" z danymi zapytania w formacie JSON w treści żą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 curl za pomocą tego wiersza poleceń (zastąp API_KEY swoim kluczem):

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 w interfejsie API po przekazaniu w zapytaniu parametru 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
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (raportowane tylko wtedy, gdy w żądaniu nie określono parametru formFactor)
• experimental_ad_count (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)
• experimental_ad_density (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)
• experimental_ad_cpu (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)
• experimental_ad_kilobytes (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)

Jeśli nie podasz wartości formFactor, wartości zostaną zagregowane we wszystkich formatach.

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

Potok danych

Zbiór danych CrUX jest przetwarzany przez potok w celu konsolidacji, agregacji i filtrowania danych, zanim zostaną one udostępnione za pomocą interfejsu API.

Średnia krocząca

Dane w raporcie na temat użytkowania Chrome to średnia krocząca z 28 dni zagregowanych danych. Oznacza to, że dane prezentowane w raporcie na temat użytkowania Chrome w danym momencie to w rzeczywistości zagregowane dane z ostatnich 28 dni.

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ącej czasu aktualizacji. Jest ona przeprowadzana codziennie w miarę możliwości.

Schemat

Interfejs CrUX API ma jeden punkt końcowy, który akceptuje żądania HTTP POST. Interfejs API zwraca obiekt record, który zawiera co najmniej 1 obiekt metrics odpowiadający danym o skuteczności dotyczącym żądanego pochodzenia 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 następującej 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 poprosić o wartości największego wyrenderowania treści na komputerze dla strony głównej dokumentacji dla deweloperó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 następującej strukturze:

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

Na przykład odpowiedź na treść żądania w poprzednim żądaniu może wyglądać 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 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.
}

Dane

metric to zestaw zagregowanych danych o wrażeniach użytkownika dotyczących pojedynczego wskaźnika wydajności strony internetowej, np. pierwszego wyrenderowania treści. Może zawierać histogram podsumowujący rzeczywiste wykorzystanie Chrome w postaci serii bins, konkretne dane percentylowe (np. p75) lub oznaczone etykietami ułamki.

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

lub

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

Przedział

bin to odrębna część danych obejmująca okres od początku do końca lub, jeśli nie podano końca, od początku do nieskończoności.

Wartości początkowa i końcowa przedziału są podawane w typie wartości danych, które reprezentuje. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczby całkowite, więc przedziały wartości tego wskaźnika będą używać liczb całkowitych 32-bitowych jako typów początku i końca. Skumulowane przesunięcie układu jest jednak mierzone w ułamkach dziesiętnych bez jednostek i jest podawane jako ułamek dziesiętny zakodowany jako ciąg znaków, dlatego jego przedziały danych będą używać ciągów znaków jako typu wartości.

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

Percentyle

Percentiles zawiera syntetyczne wartości danych w danym percentylu statystycznym. Służą one do szacowania wartości danych w przypadku odsetka użytkowników z ogólnej liczby użytkowników.

{
  "P75": value
}

Ułamki

Fractions zawiera oznaczone etykietami ułamki, które sumują się do ~1. Każda etykieta w jakiś sposób opisuje wczytanie strony, więc dane przedstawione w ten sposób można traktować jako generujące odrębne wartości, a nie wartości liczbowe, a ułamki wyrażają, jak często mierzono daną wartość.

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

Podobnie jak wartości gęstości w przedziałach histogramu, każdy znak fraction to liczba0.0 <= value <= 1.0, a ich suma wynosi około 1,0.

UrlNormalization

Obiekt reprezentujący działania normalizacyjne podjęte w celu znormalizowania adresu URL, aby zwiększyć szansę na pomyślne wyszukanie. Są to podstawowe, automatyczne zmiany, które są wprowadzane, gdy wiadomo, że wyszukiwanie podanego url_pattern nie powiedzie się. Złożone działania, takie jak przekierowania, 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. Jest on oferowany bezpłatnie. Ten limit i bieżące wykorzystanie możesz sprawdzić w konsoli Google Cloud. Ten duży limit powinien wystarczyć w większości przypadków użycia. Nie można zapłacić za zwiększenie limitu.