遷移至 Reporting API v1

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

Maud Nalpas

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

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

摘要

網站開發人員

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

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

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

報表服務開發人員

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

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

網路錯誤記錄

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

示範和程式碼

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

v0 與 v1 的差異

異動內容

• API 介面不同。

 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

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

• 報表的範圍不同。

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

維持不變的部分

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

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

v0 和 v1 之間的所有差異

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

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

這是因為報表不會像 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 版本中取得的報表。

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)。

基本遷移

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

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" }] }

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

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

觀察所有頁面

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

// 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(...)
});

CSP 報表遷移

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

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

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

延伸閱讀

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

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