本頁面由 Cloud Translation API 翻譯而成。

CrUX API

CrUX API 能讓您低延遲存取網頁和來源精細程度的匯總即時使用者體驗資料，

常見用途

CrUX API 可用來查詢特定 URI 的使用者體驗指標，例如「取得 https://example.com 來源的指標」。

CrUX API 金鑰

您必須有 Google Cloud API 金鑰，才能使用 CrUX API。您可以在「憑證」頁面中建立一個，並佈建 Chrome UX Report API 以供使用。

取得 API 金鑰後，應用程式可將查詢參數 key=[YOUR_API_KEY] 附加到所有要求網址。請參閱查詢範例。

API 金鑰可以安全地嵌入網址中，不需任何編碼。

資料模型

本節將詳細說明要求和回應中的資料結構。

錄音

網頁或網站的個別資訊。記錄可能包含專屬 ID 和特定維度組合的資料。記錄可包含一或多個指標的資料，

ID

ID 會指定應查詢的記錄。在 CrUX 中，這些 ID 是網頁和網站。

來源

如果 ID 是來源，系統會將該來源中所有網頁的資料匯總在一起。舉例來說，假設 http://www.example.com 來源含有以下 Sitemap 所配置的網頁：

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 的資料匯總在一起，因為這些網頁都是該來源下的所有網頁。

網址

如果 ID 是網址，系統只會傳回該網址的資料。再次查看 http://www.example.com 來源 Sitemap：

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

如果 ID 設為的網址值為 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 個小數點後雙重編碼，以字串表示	無單位	有三個特徵分塊的直方圖，第 75 個百分位數	cls
`first_contentful_paint`	int	毫秒	有三個特徵分塊的直方圖，第 75 個百分位數	fcp
`first_input_delay` (已淘汰)	int	毫秒	有三個特徵分塊的直方圖，第 75 個百分位數	汽車
`interaction_to_next_paint`	int	毫秒	有三個特徵分塊的直方圖，第 75 個百分位數	英寸
`largest_contentful_paint`	int	毫秒	有三個特徵分塊的直方圖，第 75 個百分位數	lcp
`experimental_time_to_first_byte`	int	毫秒	有三個特徵分塊的直方圖，第 75 個百分位數	Ttfb
`form_factors`	4 位小數 (雙位數)	百分比	從板型規格對應至分數	板型規格
`navigation_types`	4 位小數 (雙位數)	百分比	從導覽類型對應至分數	導覽類型

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`	n/a

注意：在 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)，不會變更日光節約時間。

查詢範例

查詢會以 JSON 物件的形式提交，向 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" 發出 POST 要求，並將查詢資料做為 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 殼層)。其他系統可能需要稍微修改。舉例來說，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 資料集匯總每月報表的方式類似。

每日更新

資料會在每天世界標準時間 04:00 左右更新。Google 並未提供確切的更新時間服務水準協議。這項協議每天會盡力而為。

結構定義

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` 是記錄查詢的主要 ID。只能採用下列其中一種設定：
`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 開發人員說明文件首頁最大的電腦版內容繪製值，請按照下列步驟操作：

{
  "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 是單一網路成效指標 (例如首次顯示內容所需時間) 的匯總使用者體驗資料，這可能包含一系列 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 是資料從開始到結束的獨立部分，或若沒有結束，則從開始到正無限大。

特徵代表的起始值和結束值會以其所代表指標的值類型提供。舉例來說，首次顯示內容所需時間的測量單位是毫秒，然後暴露為 int 值，因此指標特徵集將使用 int32s 作為起始和結束類型。不過，累計版面配置位移是以無單位小數測量，並以十進位編碼的形式呈現，因此指標特徵的值類型會使用字串做為值類型。

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

欄位

欄位
`start`	`(integer \| string)` 「開始」是資料特徵分塊的起點，
`end`	`(integer \| string)` 「結束」為資料特徵分塊的結尾。如果未填入結尾，特徵分塊就不會結束，且有效時間從起點到 +inf。
`density`	`number` 受這個特徵分塊針對特定指標值的使用者比例。密度會四捨五入至小數點後 4 位。

start

(integer | string)

「開始」是資料特徵分塊的起點，

end

(integer | string)

「結束」為資料特徵分塊的結尾。如果未填入結尾，特徵分塊就不會結束，且有效時間從起點到 +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

任何正規化動作後的網址。這是可合理查詢的有效使用者體驗網址。

頻率限制

對於每項 Google Cloud 專案，CrUX API 每分鐘最多只能執行 150 次查詢，而且無須付費。您可以在 Google Cloud 控制台中查看這項限制和目前的用量。這個大量配額應足以因應大多數用途的需求，而且無法針對增加的配額付費。