Опубликовано: 7 февраля 2023 г., Последнее обновление: 11 апреля 2025 г.
В этом руководстве представлен API-интерфейс Chrome UX Report (CrUX) History , который предоставляет временные ряды данных о производительности веб-сайтов. Эти данные обновляются еженедельно и позволяют просмотреть историю примерно за 6 месяцев, с 40 точками данных, расположенными с интервалом в одну неделю.
При использовании с ежедневными обновлениями из исходной конечной точки API CrUX теперь можно быстро увидеть как самые последние данные, так и события прошлых лет, что делает этот инструмент мощным средством для отслеживания изменений веб-страниц с течением времени.
Попробуйте API на этой странице.
Запрос к ежедневному API CrUX
Как уже говорилось в предыдущей статье об API CrUX , получить снимок данных поля для конкретного источника можно следующим образом:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Данный снимок включает значения плотности гистограммы и значения процентилей за определенный 28-дневный период сбора данных, в данном случае, с 27 декабря 2022 года по 23 января 2023 года.
Запрос к API истории CrUX
Для вызова конечной точки истории измените queryRecord в URL на queryHistoryRecord в команде curl . Будет работать тот же ключ API CrUX, что и для предыдущего вызова. collectionPeriodCount указывает количество возвращаемых записей временного ряда; максимальное значение — 40. Если не указано, по умолчанию используется 25.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'
Общая структура ответа похожа, но данных стало намного больше! Вместо одной точки данных теперь представлены временные ряды для полей, содержащих значения 75-го процентиля (p75) и плотности гистограммы.
{
"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 }
}
]
}
}
В этом примере временной ряд densities для интервала от 0 до 2500 мс метрики Largest Contentful Paint (LCP) имеет вид [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Каждая из этих плотностей наблюдалась в течение соответствующей записи collectionPeriods . Например, пятая плотность, 0,9183, соответствовала плотности за пятый период сбора данных, закончившийся 3 сентября 2022 года, а 0,9187 — плотности за период, закончившийся неделей позже.
Другими словами, анализ последних записей временного ряда в примере для https://web.dev показал, что с 14 августа 2022 года по 10 сентября 2022 года 91,87% загрузок страниц имели значения LCP меньше 2500 мс, 5,27% — значения от 2500 мс до 4000 мс, и 2,85% — значения больше 4000 мс.
Аналогично, существует временной ряд значений p75: значение LCP p75 за период с 14 августа 2022 года по 10 сентября 2022 года составило 1377 Это означает, что за этот период сбора данных 75% пользовательских взаимодействий имели LCP менее 1377 мс, а 25% — LCP более 1377 мс.
Хотя в примере указано всего 6 записей временного ряда и периодов сбора данных, ответы API по умолчанию предоставляют 25 записей временного ряда, а максимальное количество — 40, если в запросе указано значение "collectionPeriodCount": 40 Поскольку конечные даты каждого из этих периодов сбора данных — субботы, отстоящие друг от друга на 7 дней, значение "collectionPeriodCount": 40 охватывает 10 месяцев.
В любом заданном ответе длина временного ряда для плотности интервалов гистограммы и для значений p75 будет точно такой же, как длина массива в поле collectionPeriods : существует однозначное соответствие на основе индекса в этих массивах.
Запрос данных на уровне страницы
Помимо данных на уровне источника, API истории CrUX позволяет получить доступ к историческим данным на уровне страниц. Если ранее данные на уровне источника были доступны с помощью набора данных CrUX в BigQuery , то исторические данные на уровне страниц были доступны только в том случае, если сайты сами собирали и хранили эти данные. Новый API теперь открывает доступ к этим историческим данным на уровне страниц.
Данные на уровне страницы можно запрашивать аналогичным образом, но используя url вместо origin в полезной нагрузке:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Исторические данные на уровне страниц (и на уровне источника) подлежат тем же требованиям к доступности, что и остальная часть CrUX, поэтому страницы, в частности, могут не иметь полной исторической записи. В таких случаях «отсутствующие» данные будут представлены значением "NaN" для показателей плотности histogramTimeseries и null для показателей percentilesTimeseries . Причина различия заключается в том, что показатели плотности histogram всегда являются числами, в то время как показатели процентилей могут быть числами или строками (CLS использует строки, даже если они выглядят как числа).
Визуализируйте данные
Простейший способ визуализации данных — использование CrUX Vis, инструмента, специально созданного для демонстрации возможностей CrUX History API. Подробнее читайте в документации CrUX Vis .
Чтобы создавать подобные диаграммы самостоятельно, мы создали пример Colab . Colab, или «Colaboratory», позволяет писать и запускать код на Python прямо в браузере. Colab для CrUX History API ( источник ) использует Python для вызова API и построения графиков данных.
Этот Colab позволяет создавать диаграммы p75, трехмерные диаграммы, получать данные в табличном виде и просматривать пары запрос-ответ для API CrUX, заполнив короткую форму. Вам не обязательно быть программистом, чтобы использовать его — но вы, безусловно, можете посмотреть код на Python и модифицировать его во что-то потрясающее! Наслаждайтесь и не стесняйтесь оставлять отзывы о своих находках!
Конечно, вы не ограничены Colab или Python, и это всего лишь один из примеров использования этого нового API. Будучи HTTP-интерфейсом на основе JSON, API доступен для запросов из любой технологии.
Заключение
До появления конечной точки API истории CrUX владельцы сайтов были ограничены в объеме исторической информации, которую они могли получить из CrUX. Ежемесячные данные на уровне источника были доступны с помощью BigQuery, но еженедельные данные, а также исторические данные на уровне страниц, были недоступны. Владельцы сайтов могли самостоятельно записывать эти данные с помощью ежедневного API, но часто необходимость в этом обнаруживалась только после снижения показателей.
Предполагается, что внедрение API истории Chrome позволит владельцам сайтов лучше понимать изменения показателей своего сайта, а также послужит диагностическим инструментом при возникновении проблем. Если вы используете новый API, приветствуются ваши отзывы в группе Google Chrome UX Report (Обсуждения) .
Благодарности
Главное изображение предоставлено Дейвом Херрингом на Unsplash.