本頁面由 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 金鑰。相同的金鑰可用於 Daily 和 history 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 的板型規格表示記錄包含行動裝置載入情形的相關資訊。

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% 的網頁在記錄中第一個收集期間遇到 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 天的匯總資料，而收集期間為每週，這表示資料收集期間將會重疊。這些資料與移動平均資料類似，後續期間會包含三週的資料，另一週則有所不同。

查詢範例

查詢會以 JSON 物件的形式提交，系統會透過 POST 要求向 https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" 提交查詢，並在 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 殼層。其他系統可能需要稍微修改。舉例來說，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 值，系統會匯總所有板型規格的值。

如需更多查詢範例，請參閱使用 CrUX History API 指南。

資料管道

CrUX 資料集會透過管道處理，以整合、匯總及篩選資料，再將資料提供給 API。

累計平均

Chrome 使用者體驗報告中的資料是匯總指標 28 天的累計平均值。換句話說，Chrome 使用者體驗報告在任何特定時間點顯示的資料，實際上都是過去 28 天的資料匯總結果。

History API 包含數個收集週期，每個時間範圍都是這 28 天。由於每個收集期間都包含過去 28 天的匯總資料，而收集期間為每週，這表示資料收集期間將會重疊。這些資料與移動平均資料類似，後續期間會包含三週的資料，另一週則有所不同。

每週更新

History API 會在每週週一 04:00 左右更新，並涵蓋上一個星期六 (按照標準 2 天延遲時間) 之前的資料。其中包含前 25 週 (約 6 個月) 的資料，每週一項收集期間。

Google 並未提供確切的更新時間服務水準協議。這項協議每天會盡力而為。

結構定義

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 首頁的 Desktop 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 是單一網路成效指標 (例如首次顯示內容所需時間) 的一組使用者體驗資料。其中包含一系列 bins 的摘要直方圖，呈現 Chrome 的實際使用情況。

{
  "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 是資料從開始到結束的獨立部分，或若沒有結束，則從開始到正無限大。

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

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

欄位

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

start

(integer | string)

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

end

(integer | string)

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

string

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

頻率限制

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