此页面由 Cloud Translation API 翻译。

CrUX API

借助 CrUX API，您能够以低延迟方式访问以页面和来源粒度汇总的实时用户体验数据。

常见用例

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

CrUX API 密钥

使用 CrUX API 需要 Google Cloud 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 表示记录包含与移动设备上发生的加载有关的信息。每个维度都有一定数量的值，如果没有指定该维度，则意味着该维度将针对所有值进行汇总。例如，如果未指定设备规格，则表示记录包含发生于任何设备规格的加载的相关信息。

设备规格

最终用户用于导航到相应页面的设备类。这是一种常规类型的设备，分为 PHONE、TABLET 和 DESKTOP。

有效连接类型

有效连接类型是指导航到相应网页时设备的估算连接质量。这是一个常规类，分为 offline、slow-2G、2G、3G 和 4G。

指标

我们会将指标报告为统计汇总，采用直方图、百分位和分数形式。

浮点值会四舍五入到小数点后 4 位（请注意，cumulative_layout_shift 指标是编码为字符串的双精度浮点值，因此不会被视为浮点数，并且会在字符串中保留两位小数）。

直方图

当指标以直方图表示时，我们会显示属于该指标特定范围的网页加载所占的百分比。

示例指标的简单三分箱直方图如下所示：

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

这些数据表明，对于 38.18% 的网页加载，该示例指标的测量时间介于 0 毫秒到 1,000 毫秒之间。此直方图中不包含指标的单位，在本例中，我们假设以毫秒为单位。

此外，49.91% 的网页加载的指标值介于 1,000 毫秒到 3,000 毫秒之间，而 11.92% 的网页加载时间值大于 3,000 毫秒。

百分位

指标还可能包含可用于其他分析的百分位数。我们会报告相应指标的指定百分位值的具体指标值。它们基于完整的可用数据集，而不是最终的分箱数据，因此不一定与基于最终分箱直方图的插值百分位匹配。

{
  "percentiles": {
    "p75": 2063
  }
}

在本例中，至少有 75% 的网页加载是使用指标值 <= 2063 衡量的。

分数

分数表示可通过特定方式标记的网页加载所占的百分比。在本例中，指标值是这些标签。

例如，form_factors 指标由一个 fractions 对象组成，其中列出指定查询涵盖的外形规格（或设备）细分：

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

在此例中，3.77% 的网页加载发生在桌面设备、2.88% 的平板电脑上和 93.35% 的手机上，因此得出的总值是 100%。

指标值类型

CrUX API 指标名称	数据类型	公制单位	统计汇总	文档
`cumulative_layout_shift`	双小数编码为字符串的两位小数	无单位	包含三个分箱的直方图，百分位数为 p75	cls
`first_contentful_paint`	int	毫秒	包含三个分箱的直方图，百分位数为 p75	fcp
`first_input_delay` （已弃用）	int	毫秒	包含三个分箱的直方图，百分位数为 p75	保真
`interaction_to_next_paint`	int	毫秒	包含三个分箱的直方图，百分位数为 p75
`largest_contentful_paint`	int	毫秒	包含三个分箱的直方图，百分位数为 p75	lCP
`experimental_time_to_first_byte`	int	毫秒	包含三个分箱的直方图，百分位数为 p75	ttfb
`form_factors`	双小数位	百分比	从设备规格映射到分数	设备规格
`navigation_types`	双小数位	百分比	从导航类型到分数的映射	导航类型

BigQuery 指标名称映射

CrUX API 指标名称	BigQuery 指标名称
`cumulative_layout_shift`	`layout_instability.cumulative_layout_shift`
`first_contentful_paint`	`first_contentful_paint`
`first_input_delay`	`first_input.delay`
`interaction_to_next_paint`	`interaction_to_next_paint`
`largest_contentful_paint`	`largest_contentful_paint`
`experimental_time_to_first_byte`	`experimental.time_to_first_byte`
`navigation_types`	`navigation_types`
`form_factors`	不适用

注意：在 CrUX BigQuery 中，对于各种外形规格，每个来源的直方图密度相加高达 100%，因此我们在 API 中支持的 form_factors 指标会改为表示为 first_contentful_paint 的直方图密度。

收集期

自 2022 年 10 月起，CrUX API 包含一个 collectionPeriod 对象，该对象包含 firstDate 和 endDate 字段，分别表示汇总期的开始日期和结束日期。例如：

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

这有助于更好地了解数据，以及数据是当天已经更新，还是返回了与昨天相同的数据。

请注意，由于 CrUX API 会等待当天的完整数据，并且需要一些处理时间，然后才能在 API 中提供，因此该 API 会比今天晚大约两天。使用的时区是太平洋标准时间 (PST)，夏令时没有变化。

示例查询

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

{
  "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:queryRecord?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 值，这些值将在所有外形规格的设备上进行汇总。

如需查看更多示例查询，请参阅使用 Chrome UX Report API。

数据流水线

CrUX 数据集通过流水线进行处理，以整合、汇总和过滤数据，然后再通过 API 变为可用状态。

滚动平均值

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

这与 BigQuery 上的 CrUX 数据集汇总每月报告的方式类似。

每日动态

数据每天在世界协调时间 (UTC) 04:00 左右更新。对于更新时间，我们没有提供服务等级协议；我们每天会尽最大努力运行更新。

架构

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

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

请求正文应包含结构如下的数据：

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // 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.
}

字段
`effectiveConnectionType`	`string` 有效连接类型是一个查询维度，用于指定记录的数据应归属的有效网络类。此字段使用 Network Information API 规范中指定的值 `["offline", "slow-2G", "2G", "3G", "4G"]` 注意：如果未指定有效连接类型，则会返回一条特殊记录，其中包含针对所有有效连接类型的汇总数据。
`formFactor`	`enum` (`FormFactor`) 设备规格是一个查询维度，用于指定记录的数据应归属的设备类。此字段使用值 `DESKTOP`、`PHONE` 或 `TABLET`。注意：如果未指定外形规格，则返回一条特殊记录，其中包含所有外形规格的汇总数据。
`metrics[]`	`string` 响应中应包含的指标。如果未指定，则会返回找到的任何指标。允许使用的值：`["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]`
联合字段 `url_pattern`。`url_pattern` 是记录查询的主要标识符。它只能是下列其中一项：
`origin`	`string` `url_pattern`“origin”是指网址格式，即网站的来源。示例：`"https://example.com"`、`"https://cloud.google.com"`
`url`	`string` `url_pattern` `url` 是指任意网址的网址格式。示例：`"https://example.com/`、`https://cloud.google.com/why-google-cloud/"`

例如，要请求 Chrome 开发者文档首页的桌面设备最大 Contentful Paint 值，请使用以下代码：

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

响应正文

成功的请求会返回包含 record 对象和 urlNormalizationDetails 的响应，具体结构如下：

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

例如，对上一个请求中请求正文的响应可能是：

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

键

Key 定义了将此记录标识为唯一的所有维度。

{
  "effectiveConnectionType": string,
  "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)` 设备规格是所有用户用于访问相应网站的设备类。如果未指定设备规格，系统将返回所有设备规格的汇总数据。
`effectiveConnectionType`	`string` 有效连接类型是指所有用户在记录时遇到的常规连接类别。此字段使用 https://wicg.github.io/netinfo/#effective-connection-types 中指定的值 ["offline", "slow-2G", "2G", "3G", "4G"] 如果未指定有效连接类型，则会返回通过所有有效连接类型的汇总数据。
联合字段 `url_pattern`。网址格式是记录所适用的网址。`url_pattern` 只能是下列其中一项：
`origin`	`string` `origin` 指定此记录所属的来源。注意：指定 `origin` 时，此来源下所有网页的加载数据将汇总到来源级用户体验数据。
`url`	`string` `url` 指定此记录所属的特定网址。注意：指定 `url` 时，只有该特定网址的数据会进行汇总。

指标

metric 是针对单个网页性能指标（例如首次内容渲染）的一组汇总用户体验数据。它可能包含实际 Chrome 使用情况的汇总直方图（以一系列 bins 的形式）、特定百分位数据（例如 p75），或者可能包含带标签的分数。

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

或

{
  "fractions": {
    object (Fractions)
  }
}

字段

字段
`histogram[]`	`object (Bin)` 指标的用户体验直方图。直方图将至少有一个分箱，所有分箱的密度加起来约为 1。
`percentiles`	`object (Percentiles)` 指标的常见实用百分位。百分位值类型将与为直方图分箱指定的值类型相同。
`fractions`	`object (Fractions)` 此对象包含带标签的分数，这些分数相加等于约 1。分数四舍五入为 4 位小数。

histogram[]

object (Bin)

指标的用户体验直方图。直方图将至少有一个分箱，所有分箱的密度加起来约为 1。

percentiles

object (Percentiles)

指标的常见实用百分位。百分位值类型将与为直方图分箱指定的值类型相同。

fractions

object (Fractions)

此对象包含带标签的分数，这些分数相加等于约 1。

分数四舍五入为 4 位小数。

分箱

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

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

{
  "start": value,
  "end": value,
  "density": number
}

字段

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

start

(integer | string)

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

end

(integer | string)

End 是数据分箱的末端。如果未填充 end，则分箱没有结束时间，并且从 start 到 +inf 之间有效。

density

number

遇到指定指标的此分箱值的用户所占的比例。

密度四舍五入到小数点后 4 位。

百分位

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

{
  "P75": value
}

字段

字段
`p75`	`(integer \| string)` 75% 的网页加载所体验到的特定指标不高于此值。

p75

(integer | string)

75% 的网页加载所体验到的特定指标不高于此值。

分数

Fractions 包含带标签的分数，这些分数相加等于约 1。每个标签都以某种方式描述网页加载，因此以这种方式表示的指标可视为生成不同的值（而不是数值），并且分数表示特定不同值的衡量频率。

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

与直方图分箱中的密度值非常相似，每个 fraction 都是一个数字 0.0 <= value <= 1.0，它们相加的总和为 1.0 左右。

UrlNormalization

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

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

字段

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

originalUrl

string

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

normalizedUrl

string

任何标准化操作之后的网址。这是有效用户体验网址，可合理查询。

速率限制

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