此页面由 Cloud Translation API 翻译。

CrUX API

CrUX API 可让您以网页和来源级粒度低延迟地访问汇总的真实用户体验数据。

试试看！

常见用例

CrUX API 允许查询特定 URI 的用户体验指标，例如“获取 https://example.com 来源的指标”。

CrUX API 密钥

若要使用 CrUX API，您需要预配一个用于 Chrome UX Report API 使用的 Google Cloud API 密钥。

获取和使用 API 密钥

或在“凭据”页面中创建一个 OAuth 客户端 ID。

在您获得 API 密钥后，您的应用便可在所有请求网址后附加查询参数 key=yourAPIKey。

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。

指标

我们会以统计汇总的形式报告指标，包括直方图、百分位数和小数。

浮点值会四舍五入（请注意，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
`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`
`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 会等待当天的完整数据，因此会比当天日期落后约 2 天，而且在 API 中可用之前还需要经过一些处理时间。所用时区为美国太平洋标准时间 (PST)，不会因夏令时而发生变化。

此外，collectionPeriod 始终会显示 28 天，即使数据并非涵盖完整的 28 天（例如，网页发布时间不足 28 天）也是如此。collectionPeriod 是 CrUX 数据的汇总时间段，不一定是数据所代表的时间段。

示例查询

您可以使用 POST 请求向 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" 提交 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 命令行不允许对参数使用单引号，也不允许使用行续接符 (\)，因此需要使用双引号（使用 \" 对内部引号进行适当转义），并且使用单行。

通过在查询中传递 url 属性（而非 origin）即可通过 API 获取网页级数据：

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

如果未设置 metrics 属性，则系统会返回所有可用指标：

cumulative_layout_shift
first_contentful_paint
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 转码语法。

请求正文

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

{
  "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.
}

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

例如，如需请求 Chrome 开发者文档首页的桌面设备 Largest 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 用于定义将此记录标识为唯一的所有维度。

{
  "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` 指定此记录的来源。注意：指定 `origin` 后，所有网页中此来源下的加载数据都会汇总到来源级用户体验数据中。
`url`	`string` `url` 用于指定此记录对应的特定网址。注意：指定 `url` 后，系统只会汇总该特定网址的数据。

指标

metric 是一组针对单个 Web 性能指标（例如 First Contentful Paint）的汇总用户体验数据。它可能包含一系列 bins、特定百分位数据（例如 p75）的实际 Chrome 使用情况摘要直方图，也可能包含标记的分数。

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

或

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

字段

字段
`histogram[]`	`object (Bin)` 某个指标的用户体验直方图。直方图中至少有一个 bin，并且所有 bin 的密度总和约为 1。
`percentiles`	`object (Percentiles)` 该指标的常用百分位数。百分位的值类型将与为直方图分箱指定的值类型相同。
`fractions`	`object (Fractions)` 此对象包含标记的分数，其总和约为 1。分数会四舍五入到小数点后 4 位。

histogram[]

object (Bin)

某个指标的用户体验直方图。直方图中至少有一个 bin，并且所有 bin 的密度总和约为 1。

percentiles

object (Percentiles)

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

fractions

object (Fractions)

此对象包含标记的分数，其总和约为 1。

分数会四舍五入到小数点后 4 位。

分箱

bin 是从开始到结束（如果未指定结束日期，则为从开始到正无穷大）的离散数据部分。

分桶的起始值和结束值采用其所代表的指标的值类型。例如，首次内容渲染以毫秒为单位进行衡量并以 int 的形式显示，因此其指标分桶将使用 int32 作为其开始和结束类型。不过，累计布局偏移量以无单位的十进制数衡量，并以字符串编码的十进制数的形式显示，因此其指标分桶将使用字符串作为值类型。

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

字段

字段
`start`	`(integer \| string)` 开始是数据分桶的开头。
`end`	`(integer \| string)` “End”是数据分桶的结束。如果未填充 end，则该分桶没有结束时间，并且从 start 到 +inf 都是有效的。
`density`	`number` 对于给定指标，获得此分桶值的用户所占的比例。密度会四舍五入到小数点后 4 位。

start

(integer | string)

开始是数据分桶的开头。

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 控制台中查看此限制和当前用量。如此充足的配额应该足以满足绝大多数用例，并且无法通过付费来增加配额。