此页面由 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 指标是作为字符串编码的双精度值，因此不考虑浮点值，而是报告到字符串中的 2 位小数）。

直方图

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

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

{
  "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`	2 位小数双编码为字符串	无单位	包含三个分箱的直方图，百分位数为 p75	cls
`first_contentful_paint`	int	毫秒	包含三个分箱的直方图，百分位数为 p75	FCP
`first_input_delay` （已弃用）	int	毫秒	包含三个分箱的直方图，百分位数为 p75
`interaction_to_next_paint`	int	毫秒	包含三个分箱的直方图，百分位数为 p75	INP
`largest_contentful_paint`	int	毫秒	包含三个分箱的直方图，百分位数为 p75	LCP
`experimental_time_to_first_byte`	int	毫秒	包��三个分箱的直方图，百分位数为 p75	ttfb
`form_factors`	4 位小数	百分比	从设备规格映射到比例	外形规格
`navigation_types`	4 位小数	百分比	从导航类型映射到分数	导航类型
`round_trip_time`	int	毫秒	百分位数为 p75	rtt

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`	不适用
`round_trip_time`	不适用

注意：在 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 中。所用时区为太平洋标准时间 (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 开发者文档主页的桌面设备最大内容渲染值，请使用以下代码：

{
  "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` 有效连接类型是所有用户在遇到该记录时遇到的常规连接类别。此字段使用的值 ["offline", "slow-2G", "2G", "3G", "4G"]，详见 https://wicg.github.io/netinfo/#effective-connection-types 如果未指定有效连接类型，系统将返回所有有效连接类型的汇总数据。
联合字段 `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 以毫秒为单位进行测量，并以 int 的形式公开，因此其指标 bin 将使用 int32s 作为 start 和 end 类型。不过，累积布局偏移以无单位的小数进行衡量，并以字符串编码的形式公开，因此其指标分箱将使用字符串作为其值类型。

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

字段

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

start

(integer | string)

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

end

(integer | string)

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 控制台中查看此限额和您当前的用量。这种宽裕的配额应该足以满足绝大多数用例的需要，并且无法为增加的配额付费。