遷移至 Reporting API v1

報表 API 已推出新版本。這項功能更具隱私性，且更有可能在各瀏覽器中獲得支援。

Maud Nalpas

注意：這篇文章將說明如何遷移至新版 Reporting API (v1)。如果您是 Reporting API 的新手，或需要詳細的使用範例，請改為參閱 Reporting API 的主要文章。

Reporting API 會通知您網站在訪客使用時發生的錯誤。這項功能可讓您瞭解瀏覽器介入、瀏覽器當機、違反內容安全政策、違反 COOP/COEP、淘汰警告等問題。

Reporting API 已推出新版本。新版 API 更精簡，也更有可能在各瀏覽器中獲得支援。

注意：舊版 Reporting API 名稱為 Reporting API v0。新的 Reporting API 名稱為 Reporting API v1。

摘要

網站開發人員

如果您的網站已有報表功能：請使用新標頭 (Reporting-Endpoints) 遷移至 v1，但請保留舊版標頭一段時間 (Report-To)。請參閱遷移：程式碼範例。

如果您剛剛才在網站上新增報表功能：請只使用新的標頭 (Reporting-Endpoints)。

⚠️ 無論是哪種情況，請務必在所有可能產生報表的回應中設定 Reporting-Endpoints 標頭。

報表服務開發人員

如果您維護端點服務或自行營運，當您或外部開發人員遷移至 Reporting API v1 (Reporting-Endpoints 標頭) 時，請注意流量會增加。

請繼續閱讀下文，瞭解詳細資訊和程式碼範例！

網路錯誤記錄

注意：如果您使用網路錯誤記錄，請繼續使用 Report-To (v0)，因為 Reporting API v1 不支援網路錯誤記錄。

我們將開發新的網路錯誤記錄機制。這項功能推出後，請從 Reporting API v0 改用這項新機制。

示範和程式碼

• 示範網站：新的報表 API (第 1 版)
• 示範網站的程式碼

v0 與 v1 的差異

異動內容

• API 介面不同。

v0 (舊版)

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 使用 Report-To 標頭設定命名端點群組，並在其他標頭中使用 report-to 指令參照這些端點群組。

第 1 版 (新版)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

v1 會使用 Reporting-Endpoints 標頭設定命名端點。與 v0 一樣，它會在其他標頭中使用 report-to 指示詞來參照這些端點群組。

• 報表的範圍不同。

v0 (舊版)

在 v0 中，您只能針對部分回應設定回報端點。該來源的其他文件 (網頁) 會自動使用這些環境端點。

第 1 版 (新版)

使用 v1 時，您必須在所有可能產生報表的回應中設定 Reporting-Endpoints 標頭。

• 兩個 API 支援的報表類型相同，但 v1 不支援網路錯誤報表。詳情請參閱遷移步驟。
• 目前和未來都不會支援跨瀏覽器的 v0。v1 未來更有可能支援多個瀏覽器。

維持不變的部分

• 報表的格式和結構不變。
• 瀏覽器傳送至端點的要求仍是 Content-type application/reports+json 的 POST 要求。
• 在 v0 和 v1 中，系統都支援將特定端點對應至特定報表類型。
• default 端點的角色保持不變。

• Reporting API 1.0 對 ReportingObserver 沒有任何影響。ReportingObserver 會繼續存取所有可觀察的報表，且格式完全相同。

v0 和 v1 之間的所有差異

	舊版 Reporting API (v0) Report-To 標頭	新的 Reporting API (v1) Reporting-Endpoints標頭
瀏覽器支援	Chrome 69 以上版本和 Edge 69 以上版本。	Chrome 96 以上版本和 Edge 96 以上版本。Firefox 也支援這項功能。Safari 不反對。請參閱「瀏覽器信號」。
端點	將報表傳送至多個報表收集器 (每個端點群組定義多個網址)。	將報表傳送至特定報表收集器 (每個端點僅定義一個網址)。
API 介面	使用 `Report-To` 標頭設定命名的端點群組。	使用 `Reporting-Endpoints` 標頭設定已命名的端點。
可透過此 API 產生的報表類型	淘汰 干預 當機 COOP/COEP 內容安全政策第 3 級 (CSP 第 3 級) 網路錯誤記錄 (NEL) 如要進一步瞭解報表類型，請參閱 Reporting API 相關文章。	除了網路錯誤記錄 (NEL)：新版 Reporting API (v1) 不支援這項功能，其他都沒有變更。
報表範圍	同源內容。 文件的 Report-To 標頭會影響該來源的其他文件 (頁面)。報表的 url 欄位仍會因文件而異。	文件。 文件的 Reporting-Endpoints 標頭只會影響該文件。報表的 url 欄位仍會因文件而異。
報表隔離 (批次處理)	不同文件 (網頁) 或網站/來源如果在同一時間產生報表，且具有相同的報表端點，就會一起分批處理：這些報表會以相同的訊息傳送至報表端點。	不同文件 (網頁) 的報表不會一併傳送。即使來自相同來源的兩份文件 (網頁) 同時產生報表，且針對相同端點，也不會進行批次處理。這是一種減少隱私攻擊的機制。 系統可能會將相同文件 (網頁) 的報表一併傳送。
支援負載平衡 / 優先順序	是	否

端點開發人員：預期流量會增加

如果您已將自己的伺服器設為報表端點，或是您正在開發或維護報表收集器做為服務，請注意，該端點的流量會增加。

這是因為報表不會像 Reporting API v0 一樣，透過 Reporting API v1 進行批次處理。因此，當應用程式開發人員開始遷移至 Reporting API v1 時，報表數量會維持不變，但端點伺服器的要求量會增加。

應用程式開發人員：遷移至 Reporting-Endpoints (第 1 版)

此時該如何處理這種狀況？

使用新的 Reporting API (v1) 有幾項優點 ✅：

• 瀏覽器信號為正面，表示 v1 可預期跨瀏覽器支援 (不像 v0 僅支援 Chrome 和 Edge)。
• API 更精簡。
• 我們正在開發以新版 Reporting API (第 1 版) 為基礎的工具。

請注意下列事項：

• 如果您的網站已使用 Reporting API 第 0 版，並搭配 Report-To 標頭，請遷移至 Reporting API 第 1 版 (請參閱遷移步驟)。如果您的網站已使用內容安全政策違規的回報功能，請查看特定的CSP 回報遷移步驟。
• 如果您的網站尚未使用 Reporting API，且您現在要新增報表功能，請使用新版 Reporting API (第 1 版) (Reporting-Endpoints 標頭)。但有一個例外情況：如果您需要使用網路錯誤記錄功能，請使用 Report-To (v0)。目前 Reporting API 第 1 版不支援網路錯誤記錄。我們會開發新的網路錯誤記錄機制⏤，在該機制推出前，請使用 Reporting API v0。如果您需要與其他報表類型一併使用 Network Error Logging，請同時使用 Report-To (v0) 和 Reporting-Endpoints (v1)。v0 可提供 Network Error Logging，而 v1 則可提供所有其他類型的報表。

遷移步驟

這次遷移的目標是保留您在 v0 版本中取得的報表。

注意：由於只有 Chrome 和 Edge 支援 Reporting API v0，因此在遷移至 v1 時，您不必專注於其他瀏覽器。不過請注意，我們可能會提供更廣泛的瀏覽器支援。目前這些瀏覽器沒有追蹤錯誤，但情況可能會有所變動。

1. 步驟 1 (立即執行)：同時使用兩個標頭：Report-To (v0) 和 Reporting-Endpoints (v1)。

   這項功能可讓您：

   • 感謝 Reporting-Endpoints (第 1 版)，我們現在可以從較新的 Chrome 和 Edge 用戶端取得報表。
   • 感謝 Report-To (v0)，我們現在可以從舊版 Chrome 和 Edge 用戶端取得報表。

   支援 Reporting-Endpoints 的瀏覽器例項會使用 Reporting-Endpoints，不支援的例項則會改用 Report-To。在 v0 和 v1 中，要求和報表格式相同。

2. 步驟 2 (立即執行)：請確認所有可能產生報表的回應都已設定 Reporting-Endpoints 標頭。

   在 v0 中，您可以選擇只在部分回應中設定報表端點，而該來源的其他文件 (網頁) 會使用這個「環境」端點。在 v1 中，由於範圍設定不同，您必須在所有可能產生報表的回應中設定 Reporting-Endpoints 標頭。

3. 步驟 3 (稍後開始)：當所有或大部分使用者都更新至較新的 Chrome 或 Edge 安裝版本 (96 以上版本) 後，請移除 Report-To (v0)，只保留 Reporting-Endpoints。

   例外狀況：如果您確實需要網路錯誤記錄報表，請保留 Report-To，直到網路錯誤記錄的全新機制上線為止。

請參閱遷移說明手冊中的程式碼範例。

CSP 報表的遷移步驟

您可以透過兩種方式設定 Content-Security-Policy 違規報告：

• 使用 report-uri 指令的 CSP 標頭。這項功能支援的瀏覽器範圍廣泛，包括 Chrome、Firefox、Safari 和 Edge。系統會以 application/csp-report 內容類型傳送報表，且報表格式為 CSP 專屬。這些報表稱為「CSP 等級 2 報表」，不依賴報表 API。
• 使用 Reporting API 時，則是透過 Report-To 標頭 (舊版) 或較新的 Reporting-Endpoints (v1)。這項功能僅支援 Chrome 和 Edge。報表要求的格式與其他 Reporting API 要求相同，且內容類型也相同 (application/reports+json)。

不再建議採用第一種方法 (僅使用 report-uri)，採用第二種方法則有幾項優點。具體來說，您可以使用單一方式設定所有報表類型的報表，以及設定一般端點 (因為透過 Reporting API 產生的所有報表要求⏤ CSP 和其他⏤都採用相同格式 application/reports+json)。

不過，只有少數瀏覽器支援 report-to。因此，建議您將 report-uri 與 Reporting API 方法 (Report-To 或更佳的 Reporting-Endpoints) 搭配使用，以便從多個瀏覽器取得 CSP 違規報告。在可辨識 report-uri 和 report-to 的瀏覽器中，如果有 report-to，系統會忽略 report-uri。在只支援 report-uri 的瀏覽器中，系統只會考慮 report-uri。

1. 步驟 1 (立即執行)：如果您尚未新增，請將 report-to 與 report-uri 並列。僅支援 report-uri 的瀏覽器 (Firefox) 會使用 report-uri，而同時支援 report-to 的瀏覽器(Chrome、Edge) 會使用 report-to。如要指定您要在 report-to 中使用的已命名端點，請同時使用 Report-To 和 Reporting-Endpoints 標頭。這樣一來，您就能同時取得舊版和新版 Chrome 和 Edge 用戶端的報表。

2. 步驟 3 (稍後開始)：當所有或大部分使用者更新至較新的 Chrome 或 Edge 安裝版本 (96 以上版本) 後，請移除 Report-To (v0)，只保留 Reporting-Endpoints。保留 report-uri，即可繼續取得僅支援 report-uri 的瀏覽器的報表。

如要查看這些步驟的程式碼範例，請參閱遷移 CSP 報表。

遷移：程式碼範例

總覽

如果您使用舊版 Reporting API (v0) 取得 COOP (Cross-Origin-Opener-Policy 標頭)、COEP (Cross-Origin-Embedder-Policy) 或文件政策 (Document-Policy 標頭) 的違規報告，在遷移至 Reporting API v1 時，您不需要變更這些政策標頭。您需要從舊版 Report-To 標頭遷移至新的 Reporting-Endpoints 標頭。

如果您使用舊版 Reporting API (v0) 取得 CSP (Content-Security-Policy 標頭) 違規報告，可能需要調整 Content-Security-Policy，才能遷移至新的 Reporting API (v1)。

基本遷移

舊版程式碼 (使用 v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

新程式碼 (轉換程式碼，同時支援 v0 和 v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

如果您的網站已提供報表功能，請暫時保留 Report-To (直到大多數 Chrome 和 Edge 用戶端更新為止)，以免報表遺失。

如果您需要網路錯誤記錄功能，請保留 Report-To，直到網路錯誤記錄替代方案推出。

新驗證碼 (僅限 v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

一旦大多數 Chrome 和 Edge 用戶端更新並支援 API v1，您的程式碼就會變成下圖的樣子。

請注意，您仍可使用 v1 將特定報表類型傳送至特定端點。但每個端點只能有一個網址。

觀察所有頁面

舊版程式碼 (使用 v0)，例如 Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

在 v0 中，您只能針對部分回應設定回報端點。該來源的其他文件 (頁面) 會自動使用這些環境端點。在此情況下，為 "/" 設定的端點會用於所有回應，例如 page1。

新程式碼 (使用 v1)，例如使用 Express

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

使用 v1 時，您必須在所有可能產生報表的回應中設定 Reporting-Endpoints 標頭。

CSP 報表遷移

舊版程式碼，僅含 report-uri

Content-Security-Policy: ...; report-uri https://reports.example/main

我們不再建議只使用 report-uri。如果您的程式碼看起來像上述程式碼，請進行遷移。請參閱下方的 New 程式碼範例 (以綠色標示)。

使用 report-uri 和 report-to 指令，並搭配 Report-To (v0) 標頭的較佳舊版程式碼

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

這會更好：這個程式碼使用 report-to，這是 report-uri 的新替代項目。為了回溯相容性，系統仍會保留 report-uri；許多瀏覽器不支援 report-to，但支援 report-uri。

不過，這個做法仍有改進空間：這個程式碼使用的是 Reporting API v0 (Report-To 標頭)。遷移至 v1：請參閱下方的「新程式碼」範例 (以綠色標示)。

新程式碼，包含 report-uri 和 report-to 指令，以及 Reporting-Endpoints (v1) 標頭

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

請保留 report-uri 指令，並與 report-to 指令搭配使用，直到 report-to 指令在各瀏覽器中都支援為止。請參閱瀏覽器相容性表格。

暫時將 Report-To 和 Reporting-Endpoints 並列。大部分 Chrome 和 Edge 訪客都已升級至 96 以上版本的瀏覽器後，請移除 Report-To。

延伸閱讀

• 使用 Reporting API 監控網路應用程式 (Reporting API 的主要文章)
• 規格：舊版 Reporting API (v0)
• 規格：新的 Reporting API (第 1 版)

感謝 Ian Cleland、Eiji Kitamura 和 Milica Mihajlija 對本文的審查和建議。