如何使用 CrUX History API

本指南介绍了 Chrome UX Report (CrUX) History API 端点,此端点提供以时序显示的网页性能数据。这些数据每周更新一次,可让您了解大约 6 个月的历史记录,并以每周为间隔提供 25 个数据点。

现在,与原始 CrUX API 端点的每日更新搭配使用时,您可以快速查看最新数据和之前发生的情况,这使得这款工具成为了查看网页随时间变化的强大工具。

查询每日 CrUX API

回顾之前关于 CrUX API 的文章,您可以通过以下方式获取特定来源的字段数据快照:

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 天收集期(在本例中为 2022 年 12 月 27 日至 2023 年 1 月 23 日)的直方图密度值和百分位值。

查询 CrUX History API

如需调用历史记录端点,请在 curl 命令中将网址中的 queryRecord 更改为 queryHistoryRecord。使用与上一次调用相同的 CrUX API 密钥即可正常运行。

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

回答的总体情况与之相似,但其中包含的数据要多得多!现在,包含第 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 }
      }
    ]
  }
}

在此示例中,Largest Contentful Paint (LCP) 指标中 0 至 2500 毫秒存储分区的 densities 时间序列为 [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].。每种密度在相应的 collectionPeriods 条目期间都观察到。例如,第五个密度 0.9183 是第五个收集期(截至 2022 年 9 月 3 日)的密度,0.9187 是此后一周结束的时间段的密度。

换言之,在解读 https://web.dev 示例中的最后一个时间序列条目时,发现从 2022 年 8 月 14 日到 2022 年 9 月 10 日,91.87% 的网页加载的 LCP 值小于 2500 毫秒,5.27% 的值有 2500 毫秒到 4200 毫秒,

同样,p75 值也有一个时间序列:2022 年 8 月 14 日至 2022 年 9 月 10 日的 LCP p75 为 1377。这意味着,在此收集期内,75% 的用户体验的 LCP 低于 1377 毫秒,25% 的用户体验的 LCP 高于 1377 毫秒。

该示例仅列出了 6 个时序条目和收集期,而来自 API 的响应会提供 25 个时序条目;由于每个收集期的结束日期都是相隔 7 天的星期六,因此即为 6 个月。

在任何给定响应中,直方图分箱密度和 p75 值的时间序列长度将与 collectionPeriods 字段中的数组长度完全相同:这些数组的索引存在一对一对应关系。

查询网页级数据

除了源级数据之外,您还可通过 CrUX History API 访问历史网页级数据。虽然之前通过 BigQuery 上的 CrUX 数据集(或 CrUX 信息中心)获取了源级数据,但只有在网站本身收集和存储数据时,系统才会提供网页级历史数据。现在,该新 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 相同的资格要求,因此特别是网页可能没有完整的历史记录。在这些情况下,“缺失的”对于 histogramTimeseries 密度,数据将由 "NaN" 表示;对于 percentilesTimeseries,数据将由 null 表示。出现差异的原因是直方图密度始终是数字,而百分位数可以是数字或字符串(CLS 使用字符串,即使它们看起来像数字)。

直观呈现数据

因此,您可能会问,为什么数据要以这种方式形成?人们发现,这可以更轻松地绘制图表。例如,下图显示了 https://web.devInteraction To Next Paint (INP) 的 p75 值:

p75 值的时间序列图,显示 2022 年 11 月左右出现回归问题

在此折线图中,y 轴上的每个值都是来自 p75s 时序的 p75 值,x 轴是时间,它们被设置为每个收集期的 lastDate

这是直方图分箱时序的图表(称为三分箱图表),因为这些直方图有三个分箱。

堆叠条形图,显示良好、需要改进和不佳的相对比例随时间的变化情况。

x 轴设置为每个收集期的 lastDate。不过,这次 y 轴是 INP 指标在特定范围内的网页加载次数所占的百分比,通过堆叠条形图显示。通过 P75 图表,您可以快速了解下图表的概况,同时,在单个图表中添加多个指标或同时显示 PHONEDESKTOP 折线相对比较简单。三分箱图表可让您了解每个收集期测量的指标值的分布情况。

例如,虽然 p75 图表显示 https://web.dev 在观察期内的 INP 值几乎可以接受,但 tri-bin 图表显示,对于一小部分网页加载,INP 实际上糟糕。在这两个图表中,比较容易推断出性能下降的情况始于 10 月底,并于 11 月中旬得到解决。

为了能够自行生成此类图表,我们创建了一个示例 Colab。Colab(简称“Colaboratory”)可让您在浏览器中编写和执行 Python 代码。CrUX History API Colab来源)使用 Python 调用该 API 并绘制数据图表。

借助此 Colab,您可以制作 p75 图表和 tri-bin 图表,以表格形式获取数据,并通过填写一份简短的表单查看 CrUX API 的请求和响应对。即使您不是程序员也能使用它,但您可以查看 Python 代码并将其修改为令人惊叹的内容!请尽情享受,并随时欢迎你提供反馈!

当然,您可以使用并不仅限于 Colab 或 Python,这只是如何使用这一新 API 的一个示例。该 API 是基于 JSON 的 HTTP 端点,可通过任何技术查询。

总结

在引入 CrUX History API 端点之前,网站所有者从 CrUX 获取的历史信息有限。通过 BigQuery 和 CrUX 信息中心可获取每月源级数据,但无法提供每周数据,也无法提供网页级历史数据。网站所有者可以使用每日 API 自行记录这些数据,但通常情况下,只有在指标回归后,他们才会发现这种需求。

推出这个 CrUX History API 是希望它让网站所有者更好地了解其不断变化的网站指标,并作为出现问题时的诊断工具。如果您使用的是新 API,欢迎通过 Chrome 用户体验报告(讨论)Google 群组提供反馈。

致谢

主打图片(作者:Dave Herring,制作者:Dave Herring