遷移至 Reporting API v1

我們已推出新版 Reporting API。這項技術更注重隱私權，且瀏覽器支援的可能性較高。

Maud Nalpas

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

Reporting API 會在訪客使用網站時，通知您網站上發生的錯誤。讓您掌握瀏覽器介入、瀏覽器當機、違反內容安全政策、違反 COOP/COEP、淘汰警告等情況。

報表 API 已推出新版本。新版 API 更精簡，且更有可能獲得各瀏覽器支援。

注意：舊版 Reporting API 名為「Reporting API v0」。新版 Reporting API 名為「Reporting API v1」

。

摘要

網站開發人員

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

如果您目前正要為網站新增報表功能：請只使用新標題 (Reporting-Endpoints)。

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

報表服務開發人員

如果您維護或經營端點服務，隨著您或外部開發人員遷移至 Reporting API v1 (Reporting-Endpoints 標頭)，預計會出現更多流量。

請繼續閱讀下文，查看詳細資料和程式碼範例！

網路錯誤記錄

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

系統將開發新的網路錯誤記錄機制。該機制推出後，請從 Reporting API v0 改用新機制。

示範和程式碼

• 示範網站：新的 Reporting 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 版 (新)

使用第 1 版時，您需要在所有可能產生報表的回應中設定 Reporting-Endpoints 標頭。

• 這兩項 API 支援的報表類型相同，但有一個例外：v1 不支援網路錯誤報表。詳情請參閱遷移步驟。
• 瀏覽器不支援 v0，未來也不會支援。v1 則較有可能在未來支援多個瀏覽器。

維持不變的部分

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

• Reporting API 第 1 版不會影響 ReportingObserver。 ReportingObserver 仍可存取所有可觀察的報表，且格式相同。

v0 和 v1 之間的所有差異

	舊版 Reporting API (v0) Report-To 標頭	新版 Reporting API (v1) Reporting-Endpoints header
瀏覽器支援	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 (第 1 版) 不支援這項功能。
報表範圍	同源內容。 文件的 Report-To 標頭會影響來自該來源的其他文件 (網頁)。 報表的 url 欄位仍會因文件而異。	文件。 文件的 Reporting-Endpoints 標頭只會影響該文件。 報表的 url 欄位仍會因文件而異。
報表隔離 (批次處理)	如果不同文件 (網頁) 或網站/來源在同一時間產生報表，且具有相同的報表端點，系統就會將這些報表批次處理，並透過同一則訊息傳送至報表端點。	系統絕不會一併傳送不同文件 (網頁) 的報表。即使來自相同來源的兩份文件 (網頁) 同時為相同端點產生報表，這些報表也不會批次處理。這項機制可防範隱私權攻擊。 來自同一文件 (頁面) 的檢舉內容可能會一起傳送。
支援負載平衡 / 優先順序	是	否

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

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

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

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

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

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

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

請注意以下事項：

• 如果您的網站已使用 Reporting API v0 和 Report-To 標頭，請遷移至 Reporting API v1 (請參閱遷移步驟)。如果網站已使用內容安全政策違規的報告功能，請查看 CSP 報告的具體遷移步驟。
• 如果您的網站尚未採用 Reporting API，現在要新增報表功能：請使用新版 Reporting API (v1) (Reporting-Endpoints 標頭)。但有一個例外情況：如需使用網路錯誤記錄，請使用 Report-To (v0)。目前 Reporting API 第 1 版不支援網路錯誤記錄。我們將開發新的網路錯誤記錄機制，在此之前，請使用 Reporting API v0。如需同時使用「網路錯誤記錄」和其他報表類型，請使用 Report-To (v0) 和 Reporting-Endpoints (v1)。v0 提供「網路錯誤記錄」，v1 則提供所有其他類型的報表。

遷移步驟

這次遷移的目標是保留您在第 0 版中使用的報表。

注意：由於只有 Chrome 和 Edge 支援 Reporting API v0，因此在遷移至 v1 時，您不需要著重於其他瀏覽器。不過請注意，我們可能會擴大支援的瀏覽器範圍。目前這些瀏覽器沒有追蹤錯誤，但未來可能會有所變動。

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

   這項異動完成後，您就能：

   • 由於 Reporting-Endpoints (v1)，新版 Chrome 和 Edge 用戶端會提供報表。
   • Report-To (v0) 可讓舊版 Chrome 和 Edge 用戶端產生報表。

   支援 Reporting-Endpoints 的瀏覽器執行個體會使用 Reporting-Endpoints，不支援的執行個體則會改用 Report-To。v0 和 v1 的要求和報表格式相同。

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

   在 v0 中，您可以選擇只在部分回應中設定報表端點，而該來源的其他文件 (網頁) 會使用這個「環境」端點。在第 1 版中，由於範圍不同，您必須在所有可能產生報表的回應中設定 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 Level 2 Reports」，且不會使用 Reporting API。
• 如果是 Reporting API，則透過 Report-To 標頭 (舊版) 或較新的 Reporting-Endpoints (第 1 版)。這項功能僅支援 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，以便繼續取得僅支援這項功能的瀏覽器報表。

如需這些步驟的程式碼範例，請參閱「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 (第 0 版) 取得 CSP (Content-Security-Policy 標頭) 的違規報表，可能需要調整 Content-Security-Policy，才能遷移至新版 Reporting API (第 1 版)。

基本遷移

舊版程式碼 (含 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 ，直到網路錯誤記錄替代方案推出為止。

新程式碼 (僅限第 1 版)

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

日後，當大多數 Chrome 和 Edge 用戶端更新完畢並支援 API v1 時，您的程式碼可能就會像這樣。

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

觀察所有網頁

舊版程式碼 (使用 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(...)
});

使用第 1 版時，您需要在所有可能產生報表的回應中設定 Reporting-Endpoints 標頭。

CSP 報表遷移

舊版程式碼，僅含 report-uri

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

report-uri不再建議單獨使用。 如果您的程式碼如上所示，請遷移。請參閱下方的「新程式碼範例」(以綠色標示)。

更完善的舊版程式碼，包含 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-to 指令前，請將 report-uri 指令與 report-to 指令放在一起。請參閱瀏覽器相容性表格。

暫時將 Report-To 放在 Reporting-Endpoints 旁邊。當大多數 Chrome 和 Edge 訪客升級至 96 以上的瀏覽器版本後，請移除 Report-To。

延伸閱讀

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

感謝 Ian Clelland、北村英二和 Milica Mihajlija 審查本文並提供建議。