此页面由 Cloud Translation API 翻译。

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 返回的收集期日期的顺序显示，其中第一个点是最早的时间段，最后一个点是最近的收集期。

一个示例指标的三个分箱直方图如下所示：

{
  "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
round_trip_time
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 个月）的数据，每周一个收集期。

对于更新时间，我们没有相应的服务等级协议；我们每天都会尽力而为。

架构

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

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

CrUX History API 使用与每日 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 是单个网页性能指标（例如首次内容渲染）的一组用户体验数据。其中包含真实 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 是数据中从开始到结束的离散部分，或者如果从开始到正无穷大没有指定结束值。

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

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

字段

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

start

(integer | string)

起始位置是数据箱的起始位置。

end

(integer | string)

End 是数据箱的末端。如果未填充结束值，则分箱没有结束值，并且从 start 到 +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% 的网页加载经历的指定指标值等于或低于此值的时间序列。

UrlNormalization

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

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

字段

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

originalUrl

string

在执行任何标准化操作之前请求的原始网址。

normalizedUrl