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 金鑰。同一個金鑰可用於每日和歷史 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% 的網頁載入情形，記錄中第一個資料收集期間，指標值介於 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 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 天的匯總資料，且收集期間為每週，因此這意味著資料收集期間會重疊。這與資料移動平均值相似，在接下來的週期中納入了三週的資料量，但有一週的資料不同。

查詢範例

查詢是透過對 https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" 提出的 POST 要求提交，並以 JSON 物件形式在 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"]}'

如要使用網頁層級資料，請在查詢中傳遞 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
• round_trip_time
• form_factors (只有在要求中未指定 formFactor 時才回報)

如未提供 formFactor 值，系統就會在所有板型規格中匯總這些值。

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

資料管道

CrUX 資料集會透過管道處理，用於合併、匯總及篩選資料，然後再透過 API 提供。

累計平均

Chrome 使用者體驗報表中的資料是 28 天的匯總指標累計平均值。也就是說，任何特定時間點在 Chrome 使用者體驗報告中顯示的資料，都是過去 28 天的資料匯總在一起。

History API 內含多個收集週期，每個時間範圍為這 28 天。由於每個收集期間都包含過去 28 天的匯總資料，且收集期間為每週，因此這意味著資料收集期間會重疊。這與資料移動平均值相似，在接下來的週期中納入了三週的資料量，但有一週的資料不同。

每週更新

History API 會在每週一的世界標準時間 04:00 左右更新，其中包含截至上週六為止的資料 (根據標準 2 天的延遲時間)。這份資料包含過去 25 週 (約 6 個月) 的資料，每週一項資料收集期間。

我們並不提供更新時間的服務水準協議，會每天盡力執行。

結構定義

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 首頁的桌面 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內 Google Chrome 使用狀況的摘要直方圖。

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

或

"fractionTimeseries": {
  object (Fractions)
}

欄位
histogramTimeseries[]	object (Bin) 指標的使用者體驗時間序列直方圖。時間序列直方圖至少會有 1 個特徵分塊，所有特徵分塊的密度總和等於約 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) End 為資料特徵分塊的結尾。如果未填入結尾，特徵分塊沒有結尾，且從頭到 +inf 有效。
densities	array[number] 在這個生命週期中，遇到指定指標值的使用者比例時間序列。 密度會四捨五入至小數點後 4 位。

百分位數

Percentiles 包含特定統計百分位數的指標綜合值。可用來估算使用者在總人數中所佔的百分比。

{
  "P75": value
}

欄位
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% 的網頁載入頁面，您呈現的時間序列值維持在這個值或低於這個值。

UrlNormalization

這個物件代表為網址正規化而採取的正規化操作，以便提高查詢成功的機率。這些是在查詢提供的 url_pattern 時執行的簡單自動化變更，是會失敗的。系統不會處理以下複雜的操作，例如追蹤重新導向。

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

欄位
originalUrl	string 尚未進行任何正規化動作之前的原始要求網址。
normalizedUrl	string 任何正規化動作後的網址。這是可供查理的有效使用者體驗網址。

頻率限制

CrUX History API 與 CrUX API 一樣的限制，不論是 Google Cloud 專案，每項 API 每分鐘查詢 150 次都相同 (免付費)。如要查看這項限制和目前的用量，請前往 Google Cloud 控制台。這麼多的配額應該足以應付大多數的用途，而且您無法為提高配額付費。