Эта страница переведена с помощью Cloud Translation API.

API истории CruX

API истории CrUX обеспечивает доступ с малой задержкой к шестимесячным историческим данным о реальном пользовательском опыте с детализацией страницы и источника.

Общий случай использования

API истории CrUX позволяет запрашивать исторические показатели пользовательского опыта для определенного URI, например «Получить исторические тенденции UX для источника https://example.com ».

History API имеет ту же структуру, что и ежедневный CrUX API, за исключением того, что значения задаются в массиве, а ключи помечены именами во множественном числе (например, histogramTimeseries вместо histogram или p75s вместо p75 ).

Ключ API CruX

Как и в случае с ежедневным API, для использования API истории CrUX требуется ключ Google Cloud API. Один и тот же ключ можно использовать для ежедневного и исторического API.

Вы можете создать его на странице «Учетные данные» и подготовить его для использования Chrome UX Report API .

Получив ключ API, ваше приложение может добавить параметр запроса key=[YOUR_API_KEY] ко всем URL-адресам запроса. См. Примеры запросов .

Ключ API можно безопасно встраивать в URL-адреса; ему не нужна никакая кодировка.

Модель данных

В этом разделе подробно описана структура данных в запросах и ответах.

Записывать

Отдельный фрагмент информации о странице или сайте. Запись может содержать данные, специфичные для идентификатора и определенной комбинации измерений. Запись может содержать данные для одной или нескольких метрик.

Идентификаторы

Идентификаторы указывают, какие записи следует искать. В CrUX этими идентификаторами являются веб-страницы и веб-сайты.

Источник

Если идентификатор является источником, все данные, имеющиеся для всех страниц в этом источнике, объединяются вместе. Например, предположим, что в источнике http://www.example.com были страницы, представленные в этой карте сайта:

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

Это будет означать, что при запросе отчета Chrome UX с источником, установленным на http://www.example.com , данные для http://www.example.com/ , http://www.example.com/foo.html и http://www.example.com/bar.html будут возвращены вместе, поскольку все это страницы этого источника.

URL-адреса

Если идентификатором является URL-адрес, будут возвращены только данные для этого конкретного URL-адреса. Снова взглянем на исходную карту сайта http://www.example.com :

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

Если идентификатор установлен на URL со значением http://www.example.com/foo.html , будут возвращены только данные для этой страницы.

Размеры

Измерения определяют конкретную группу данных, по которым агрегируется запись. Например, форм-фактор PHONE указывает на то, что запись содержит информацию о нагрузках, произошедших на мобильном устройстве.

API истории CrUX доступен только в совокупности по измерениям форм-фактора. Это общий класс устройств, разделенный на PHONE , TABLET и DESKTOP .

Метрика

Мы сообщаем показатели во временных рядах статистических агрегатов, которые представляют собой гистограммы, процентили и дроби.

Гистограммы

Когда метрики выражаются в виде массива гистограмм, каждая запись временного ряда представляет собой процент загрузок страниц, для которых метрика попала в интервал, пропорционально всем. Точки данных представлены в порядке дат периода сбора данных, также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

Простая гистограмма с тремя интервалами для примера метрики выглядит следующим образом:

{
  "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]
    }
  ],
}

Эти данные показывают, что для 91,90% загрузок страниц значение метрики примера составляло от 0 мс до 2500 мс для первого периода сбора в истории, за ним следовали 92,03%, 91,94%... Единицы метрики не содержатся в этой гистограмме. в данном случае мы будем считать миллисекунды.

Кроме того, в 5,21% загрузок страниц значение показателя примера составляло от 2500 до 4000 мс в первый период сбора в истории, а в 2,88% загрузок страниц наблюдалось значение, превышающее 4000 мс в первый период сбора в истории.

процентили

Метрики также могут содержать временные ряды процентилей, которые могут быть полезны для дополнительного анализа.

Точки данных представлены в порядке дат периода сбора данных, также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

Эти процентили могут отображать конкретные значения показателей в заданном процентиле для этого показателя. Они основаны на полном наборе доступных данных, а не на окончательных распределенных данных, поэтому они не обязательно соответствуют интерполированному процентилю, основанному на окончательной объединенной гистограмме.

Фракции

Метрики могут быть выражены как временные ряды помеченных фракций; каждая метка определенным образом описывает загрузку страницы. Точки данных представлены в порядке дат периода сбора данных, также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

Пример:

{    
  "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]}
  }
}

В этом примере самые последние данные показывают, что 14,21% загрузок страниц приходилось на настольные компьютеры, а 82,88% — на телефоны.

Типы значений метрик

Поскольку API истории CrUX использует одни и те же типы значений метрик, вы можете обратиться к ежедневной документации по типам значений метрик CrUX API для получения более подробной информации.

Соответствие метрике

В зависимости от критериев приемлемости источник или URL-адрес могут иметь право только на некоторые периоды сбора данных, охватываемые API истории CrUX. В этих случаях API истории CrUX вернет "NaN" для плотностей histogramTimeseries и null для percentilesTimeseries для периодов сбора, по которым нет подходящих данных. Причина различия в том, что плотности гистограмм всегда представляют собой числа, а процентили могут быть числами или строками (CLS использует строки, даже если они выглядят как числа).

Например, если во втором периоде не было подходящих данных, это будет выглядеть так:

{
  "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]
  },
}

Для URL-адресов или источников, которые с течением времени попадают в список допустимых, вы можете заметить множество пропущенных записей.

Периоды сбора

API истории CrUX содержит объект collectionPeriods с массивом полей firstDate и endDate , представляющих даты начала и окончания каждого окна агрегации. Например:

    "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 }
      }
    ]

Эти периоды сбора расположены в порядке возрастания и представляют собой диапазон дат каждой точки данных в других разделах ответа.

API истории обновляется каждый понедельник и содержит данные до предыдущей субботы (согласно стандартной двухдневной задержке). Он содержит данные за предыдущие 25 недель — один период сбора в неделю.

Поскольку каждый период сбора содержит агрегированные данные за предыдущие 28 дней, а периоды сбора составляют каждую неделю, это означает, что периоды сбора будут перекрываться. Они похожи на скользящее среднее данных: данные за три недели включаются в каждый последующий период, а данные за одну неделю отличаются.

Примеры запросов

Запросы отправляются как объекты JSON с использованием запроса POST к https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" с данными запроса в виде объекта JSON в теле POST.

Обратите внимание на использование queryHistoryRecord вместо queryRecord ежедневного API CrUX.

Пример тела:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Например, это можно вызвать из curl с помощью следующей командной строки (заменив 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"]}'

Примечание. Предыдущий пример предназначен для систем на базе macOS или Linux, включая оболочку Git BASH для Windows. Другие системы могут потребовать небольших модификаций. Например, командная строка cmd.exe не допускает ни одинарных кавычек для параметров, ни продолжения строк ( \ ), поэтому требует использования двойных кавычек (при необходимости экранируя внутренние кавычки с помощью \" ), а также использования одной строки.

Данные уровня страницы доступны через API, если в запросе передается свойство url вместо origin :

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Если свойство metrics не установлено, будут возвращены все доступные метрики:

cumulative_layout_shift
first_contentful_paint
first_input_delay
interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors (сообщается только в том случае, если в запросе не указан formFactor )

Если значение formFactor не указано, значения будут агрегированы по всем форм-факторам.

Дополнительные примеры запросов см. в руководстве «Использование API истории CrUX» .

Конвейер данных

Набор данных CrUX обрабатывается через конвейер для консолидации, агрегирования и фильтрации данных, прежде чем они станут доступны через API.

Скользящее среднее

Данные в отчете Chrome UX представляют собой 28-дневное скользящее среднее агрегированных показателей. Это означает, что данные, представленные в отчете Chrome UX в любой момент времени, на самом деле представляют собой совокупные данные за последние 28 дней.

API истории содержит несколько периодов сбора данных, каждый из которых охватывает 28 дней. Поскольку каждый период сбора содержит агрегированные данные за предыдущие 28 дней, а периоды сбора составляют каждую неделю, это означает, что периоды сбора будут перекрываться. Они похожи на скользящее среднее данных: данные за три недели включаются в каждый последующий период, а данные за одну неделю отличаются.

Еженедельные обновления

API истории обновляется каждый понедельник около 04:00 UTC и содержит данные до предыдущей субботы (в соответствии со стандартной двухдневной задержкой). Он содержит данные за предыдущие 25 недель (приблизительно 6 месяцев), один период сбора в неделю.

Для времени обновления не существует соглашения об уровне обслуживания; он выполняется каждый день с максимальной отдачей.

Схема

Для API истории CrUX существует единственная конечная точка, которая принимает HTTP-запросы POST . API возвращает record , содержащую одну или несколько metrics , соответствующих данным производительности запрошенного источника или страницы.

HTTP-запрос

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

URL-адрес использует синтаксис транскодирования gRPC .

Тело запроса

API истории CrUX использует те же тела запросов, что и ежедневный API CrUX , за исключением отсутствия поддержки поля запроса effectiveConnectionType .

Например, чтобы запросить значения наибольшего содержимого рабочего стола для домашней страницы web.dev:

{
  "origin": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Тело ответа

Успешные запросы возвращают ответы с объектом record и urlNormalizationDetails в следующей структуре:

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

Например, ответ на тело запроса в предыдущем запросе может быть таким:

{
  "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 }
      }, {
        ...
      }
    ]
  }
}

Ключ

Key определяет все измерения, которые идентифицируют эту запись как уникальную.

{
  "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.
}

Поля
`formFactor`	`enum ( FormFactor )` Форм-фактор — это класс устройства, который использовали все пользователи для доступа к сайту по этой записи. Если форм-фактор не указан, будут возвращены агрегированные данные по всем форм-факторам.
`url_ pattern` поля объединения. Шаблон URL-адреса — это URL-адрес, к которому применяется запись. `url_ pattern` может быть только одним из следующих:
`origin`	`string` Происхождение указывает происхождение, для которого предназначена эта запись. Примечание. При указании источника данные о загрузках под этим источником на всех страницах объединяются в данные взаимодействия с пользователем на уровне источника.
`url`	`string` `url` указывает конкретный URL-адрес, для которого предназначена эта запись. Примечание. При указании `url` будут агрегированы данные только для этого конкретного URL-адреса.

Метрики

metric — это набор данных о пользовательском опыте для одной метрики веб-производительности, например первой отрисовки контента. Он содержит сводную гистограмму реального использования Chrome в виде серии bins .

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

или

"fractionTimeseries": {
  object (Fractions)
}

Поля

Поля
`histogramTimeseries[]`	`object ( Bin )` Гистограмма временных рядов пользовательского опыта для метрики. Гистограмма временных рядов будет иметь хотя бы один интервал, а плотность всех интервалов составит в сумме ~1. Отсутствующие значения для этого конкретного периода сбора будут помечены как `"NaN"` .
`percentilesTimeseries`	`object ( Percentiles )` Общие полезные процентили Метрики. Тип значения для процентилей будет таким же, как типы значений, заданные для ячеек гистограммы. Отсутствующие значения для этого конкретного периода сбора будут помечены как `null` .
`fractionTimeseries`	`object ( Fractions )` Этот объект содержит временные ряды помеченных дробей, сумма которых составляет ~1 на каждую запись. Дроби округляются до 4 знаков после запятой. Отсутствующие записи обозначаются как «NaN» для всех дробей.

histogramTimeseries[]

object ( Bin )

Гистограмма временных рядов пользовательского опыта для метрики. Гистограмма временных рядов будет иметь хотя бы один интервал, а плотность всех интервалов составит в сумме ~1.

Отсутствующие значения для этого конкретного периода сбора будут помечены как "NaN" .

percentilesTimeseries

object ( Percentiles )

Общие полезные процентили Метрики. Тип значения для процентилей будет таким же, как типы значений, заданные для ячеек гистограммы.

Отсутствующие значения для этого конкретного периода сбора будут помечены как null .

fractionTimeseries

object ( Fractions )

Этот объект содержит временные ряды помеченных дробей, сумма которых составляет ~1 на каждую запись.

Дроби округляются до 4 знаков после запятой.

Отсутствующие записи обозначаются как «NaN» для всех дробей.

Бин

bin — это дискретная часть данных, охватывающая от начала до конца или, если конец не указан, от начала до положительной бесконечности.

Начальное и конечное значения интервала задаются в типе значения метрики, которую он представляет. Например, первая отрисовка содержимого измеряется в миллисекундах и отображается как целые числа, поэтому его метрические ячейки будут использовать int32 для начальных и конечных типов. Однако совокупный сдвиг макета измеряется в десятичных дробях без единиц измерения и отображается как десятичное число, закодированное в виде строки, поэтому его метрические ячейки будут использовать строки в качестве типа значения.

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

Поля

Поля
`start`	`(integer \| string)` Начало — начало бункера данных.
`end`	`(integer \| string)` Конец — конец бункера данных. Если конец не заполнен, то интервал не имеет конца и действителен от начала до +inf.
`densities`	`array[number]` Временной ряд доли пользователей, которые испытали значение этого интервала для данного показателя. Плотности округлены до 4 десятичных знаков.

start

(integer | string)

Начало — начало бункера данных.

end

(integer | string)

Конец — конец бункера данных. Если конец не заполнен, то интервал не имеет конца и действителен от начала до +inf.

densities

array[number]

Временной ряд доли пользователей, которые испытали значение этого интервала для данного показателя.

Плотности округлены до 4 десятичных знаков.

процентили

Percentiles содержат синтетические значения показателя для данного статистического процентиля. Они используются для оценки значения показателя, воспринимаемого процентом пользователей от общего числа пользователей.

{
  "P75": value
}

Поля

Поля
`p75s`	`array[(integer \| string)]` Временные ряды значений, при которых 75 % загрузок страниц имели заданную метрику, равную или меньшую этого значения.

p75s

array[(integer | string)]

Временные ряды значений, при которых 75 % загрузок страниц имели заданную метрику, равную или меньшую этого значения.

Фракции

Fractions содержат временные ряды помеченных дробей, сумма которых составляет ~1 на каждую запись. Каждая метка каким-то образом описывает загрузку страницы, поэтому метрики, представленные таким образом, можно рассматривать как производящие отдельные значения вместо числовых значений, а дроби выражают частоту измерения определенного отдельного значения.

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Подобно значениям плотности в интервалах гистограммы, каждая fraction представляет собой число 0.0 <= value <= 1.0 , и в сумме они дают ~1,0. Если метрика недоступна для определенного периода сбора, то соответствующая запись будет «NaN» во всех массивах дробей.

Поля

Поля
`p75s`	`array[(integer \| string)]` Временные ряды значений, при которых 75% загрузок страниц имели данную метрику на уровне или ниже этого значения.

p75s

array[(integer | string)]

Временные ряды значений, при которых 75% загрузок страниц имели данную метрику на уровне или ниже этого значения.

Нормализация URL

Объект, представляющий действия по нормализации, предпринятые для нормализации URL-адреса, чтобы повысить вероятность успешного поиска. Это простые автоматические изменения, которые вносятся в случае, если поиск по предоставленному url_pattern , как известно, не удался. Сложные действия, такие как следующие перенаправления, не обрабатываются.

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

Поля

Поля
`originalUrl`	`string` Исходный запрошенный URL-адрес до любых действий по нормализации.
`normalizedUrl`	`string` URL-адрес после любых действий по нормализации. Это действительный URL-адрес пользовательского интерфейса, который вполне можно найти.

originalUrl

string

Исходный запрошенный URL-адрес до любых действий по нормализации.

normalizedUrl

string

URL-адрес после любых действий по нормализации. Это действительный URL-адрес пользовательского интерфейса, который вполне можно найти.

Ограничения ставок

API истории CrUX имеет тот же лимит, что и API CrUX: 150 запросов в минуту для каждого проекта Google Cloud для любого API, который предлагается бесплатно. Этот лимит и текущее использование можно увидеть в Google Cloud Console . Этой щедрой квоты должно быть достаточно для подавляющего большинства случаев использования, и невозможно заплатить за увеличение квоты.