CrUX History API

借助 CrUX History API，能够以低延迟方式访问六个月内以页面和来源为粒度的真实用户体验历史数据。

常见用例

借助 CrUX History API，您可以查询特定 URI 的历史用户体验指标，例如“获取 https://example.com 源的历史用户体验趋势”。

History API 遵循与每日 CrUX API 相同的结构，但值是以数组形式提供的，并且键使用复数名称进行标记（例如，使用 histogramTimeseries 而不是 histogram，或 p75s 而不是 p75）。

CrUX API 密钥

与每日 API 一样，使用 CrUX History API 也需要 Google Cloud API 密钥。同一密钥可用于每日 API 和历史记录 API。

您可以在凭据页面中创建一个，然后预配该密钥以供 Chrome UX Report API 使用。

在您获得 API 密钥后，您的应用便可将查询参数 key=[YOUR_API_KEY] 附加到所有请求网址中。请参阅查询示例。

API 密钥可以安全地嵌入网址中，而无需进行任何编码。

数据模型

本部分详细介绍了请求和响应中的数据结构。

记录

关于网页或网站的独立信息。记录可以包含特定于标识符的数据和特定于维度组合的数据。一条记录可以包含一个或多个指标的数据。

标识符

标识符指定应查找哪些记录。在 CrUX 中，这些标识符是网页和网站。

原点

当标识符是来源时，该来源中所有网页的所有数据都会汇总在一起。例如，假设 http://www.example.com 源包含如下站点地图所列的网页：

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

这意味着，在来源设为 http://www.example.com 的情况下查询 Chrome 用户体验报告时，系统会返回 http://www.example.com/、http://www.example.com/foo.html 和 http://www.example.com/bar.html 的数据并将它们汇总到一起，因为这些都是该来源下的网页。

网址

如果标识符是网址，则只会返回该特定网址的数据。再次查看 http://www.example.com 源站点地图：

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

如果将标识符设置为带有 http://www.example.com/foo.html 值的网址，则系统将仅返回该网页的数据。

维度

维度可用于识别记录汇总时所依据的一组特定数据。例如，如果外形规格为 PHONE，则表示记录包含发生在移动设备上的加载的相关信息。

CrUX History API 只能按设备规格维度进行汇总。这是一种常规类型的设备，分为 PHONE、TABLET 和 DESKTOP。

注意：与每日 API 不同，CrUX History API 不包含根据有效连接类型 (ECT) 汇总的数据。

指标

我们会按统计汇总的时间序列（直方图、百分位数和分数）报告指标。

直方图

当指标以直方图数组表示时，每个时序条目表示相应指标归入某个区间的网页加载次数占全部加载次数的比例。数据点会按照 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 毫秒到 2,500 毫秒之间的示例指标值，其次是 92.03%、91.94%... 此直方图中不包含指标的单位，在本例中，我们采用毫秒。

此外，5.21% 的网页加载在历史记录的第一个收集期遇到了 2,500 毫秒到 4,000 毫秒之间的示例指标值，而 2.88% 的网页加载在历史记录的第一个收集期遇到了超过 4,000 毫秒的值。

百分位

指标还可能包含百分位数时序，这对于其他分析很有用。

数据点会按照 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% 的网页加载来自手机。

指标值类型

由于 CrUX History API 使用相同的指标值类型，因此如需了解详情，请参阅每日 CrUX API 指标值类型文档。

指标资格条件

根据相关资格条件，来源或网址可能只能在 CrUX History API 涵盖的部分收集期内使用。在这些情况下，CrUX History API 将针对 histogramTimeseries 密度返回 "NaN"；对于没有符合条件的数据的收集期，percentilesTimeseries 返回 null。造成差异的原因是直方图密度始终是数字，而百分位数可以是数字或字符串（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]
  },
}

您可能会发现，随着时间的推移，某些网址或来源会逐渐符合条件或不再符合条件。

收集期

CrUX History API 包含一个 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 }
      }
    ]

这些收集期按升序排列，表示响应其他部分中每个数据点的日期范围。

History API 每周一更新，包含截至上周六的数据（根据标准的 2 天延迟）。它包含过去 25 周的数据 - 每周一个收集期。

由于每个收集期都包含之前 28 天的汇总数据，而收集期每周都是一次，这意味着收集期会重叠。它们类似于数据的移动平均值，即后续的每个时间段包含三周的数据，而一周的数据会有所不同。

示例查询

使用对 https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" 的 POST 请求以 JSON 对象的形式提交查询，并在 POST 正文中将查询数据作为 JSON 对象提交。

请注意，使用 queryHistoryRecord 取代了每日 CrUX API 的 queryRecord。

正文示例：

{
  "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 的系统，包括适用于 Windows 的 Git BASH shell。其他系统可能需要略有修改。例如，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 值，这些值将在所有外形规格的设备上进行汇总。

如需查看更多示例查询，请参阅使用 CrUX History API 指南。

数据流水线

CrUX 数据集通过流水线进行处理，以整合、汇总和过滤数据，然后才通过 API 提供。

滚动平均值

Chrome 用户体验报告中的数据是汇总指标的 28 天滚动平均值。也就是说，Chrome 用户体验报告在任何给定时间显示的数据实际上是过去 28 天的数据汇总。

History API 包含许多收集期，每个收集期跨越这 28 天。由于每个收集期都包含之前 28 天的汇总数据，而收集期每周都是一次，这意味着收集期会重叠。它们类似于数据的移动平均值，即后续的每个时间段包含三周的数据，而一周的数据会有所不同。

每周动态

History API 会在每周一世界协调时间 (UTC) 凌晨 04:00 左右更新，包含截至上周六的数据（根据 2 天标准延迟）。它包含过去 25 周（大约 6 个月）的数据，每周一个收集期。

对于更新时间，我们没有提供服务等级协议；我们每天会尽最大努力运行更新。

注意：数据在每周一世界协调时间 (UTC) 04:00 左右更新后一周内的数据不会存在差异，重复的调用会产生相同的结果。

架构

CrUX History API 只有一个端点，可接受 POST HTTP 请求。该 API 会返回一个 record，其中包含一个或多个 metrics，与所请求的源或网页的效果数据相对应。

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

CrUX History API 使用的请求正文与 Daily CrUX API 相同，但不支持 effectiveConnectionType 请求字段。

例如，要请求 web.dev 主页的桌面设备 Largest Contentful Paint 值，请使用以下代码：

{
  "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_pattern 只能是下列其中一项：
origin	string Origin 用于指定此记录所属的来源。 注意：指定来源时，此来源下所有网页的加载数据将汇总到来源级别的用户体验数据。
url	string url 指定此记录所属的特定网址。 注意：指定 url 时，只有该特定网址的数据会进行汇总。

指标

metric 是针对单个网页性能指标（例如首次内容渲染）的一组用户体验数据。它包含以一系列 bins 形式呈现的真实 Chrome 使用情况摘要直方图。

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

或

"fractionTimeseries": {
  object (Fractions)
}

字段
histogramTimeseries[]	object (Bin) 指标的用户体验时序直方图。时间序列直方图将至少有一个分箱，所有分箱的密度加起来约为 1。 该特定收集期的缺失值将被标记为 "NaN"。
percentilesTimeseries	object (Percentiles) 指标的常见实用百分位。百分位值类型将与为直方图分箱指定的值类型相同。 该特定收集期的缺失值将被标记为 null。
fractionTimeseries	object (Fractions) 此对象包含带标签的分数时间序列，每个条目加起来约为 1 个。 分数四舍五入为 4 位小数。 缺失条目在所有分数中都表示为“NaN”。

分箱

bin 是从开始到结束（如果没有开始到正无穷大）的数据的离散部分。

分箱的起始值和结束值通过其所代表的指标的值类型指定。例如，First Contentful Paint 以毫秒为单位，并以整数形式公开，因此其指标分箱将使用 int32s 作为其 start 和 end 类型。不过，累计布局偏移是用无单位小数衡量的，并作为字符串编码的十进制数提供，因此其指标分箱将使用字符串作为其值类型。

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

字段
start	(integer | string) Start 是数据分箱的起始位置。
end	(integer | string) End 是数据分箱的末端。如果未填充 end，则分箱没有结束时间，并且从 start 到 +inf 之间有效。
densities	array[number] 遇到指定指标的此分箱值的用户所占比例的时间序列。 密度四舍五入到小数点后 4 位。

百分位

Percentiles 包含指定统计百分位上的指标的合成值。这些指标用于估算指标值，即用户总数中一定比例的用户所体验到的指标值。

{
  "P75": value
}

字段
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% 的网页加载遇到的指定指标等于或低于此值的值的时间序列。

UrlNormalization

对象，表示为了提高网址成功查找几率而对网址进行标准化所采取的标准化操作。这些是简单的自动更改，在查询提供的 url_pattern（已知会失败）时执行。系统不会处理跟踪重定向等复杂操作。

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

字段
originalUrl	string 在执行任何标准化操作之前请求的原始网址。
normalizedUrl	string 任何标准化操作之后的网址。这是有效用户体验网址，可合理查询。

速率限制

CrUX History API 与 CrUX API 具有相同的限制，对于这两个 API，每个 Google Cloud 项目每分钟 150 次查询均免费。您可以在 Google Cloud 控制台中查看此限制以及您当前的用量。这种宽裕的配额应该足以满足绝大多数使用场景，而且购买后增加配额是不可能的。