本頁面由 Cloud Translation API 翻譯而成。

遷移至 Reporting API v1

Reporting API 已推出新版本。安全更有保障，且可能跨瀏覽器支援。

Maud Nalpas

Reporting API 會在訪客使用網站時通知您，這提供了瞭解瀏覽器介入措施、瀏覽器異常終止、違反《Content-Security-Policy》違規事項， COOP/COEP 違規、淘汰警告等

Reporting API 已推出新版本。新 API 不僅精簡，。

摘要

網站開發人員

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

如果要在網站上加入報表功能：請只使用新標題 (Reporting-Endpoints)。

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

報表服務開發人員

如果您維護端點服務或自行營運，則預期流量會隨著您或外部開發人員遷移至 Reporting API v1 (Reporting-Endpoints 標題)。

請繼續閱讀下方的詳細資訊和範例程式碼！

網路錯誤記錄

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

即將開發網路錯誤記錄的新機制。待更新發布後，從 Reporting API 第 0 版改用這個新機制。

示範和代碼

示範網站：新版 Reporting API (v1)
示範網站的程式碼

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 指令則可參照這些端點群組。

v1 (新推出)

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

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

報表範圍不同，

v0 (舊版)

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

v1 (新推出)

使用 v1 時，您需要為所有可能產生的回應設定 Reporting-Endpoints 標頭報表。

兩個 API 支援相同的報表類型，但有一個例外：v1 不支援網路錯誤報告。詳情請參閱遷移步驟。
第 0 版未支援，也不支援所有瀏覽器。較有可能在。

維持不變的項目

報表的格式和結構不會改變。
瀏覽器傳送至端點的要求仍是 Content-type 的 POST 要求 application/reports+json。
v0 和 v1 都支援將某些端點對應至特定報表類型。
default 端點的角色未變更。
Reporting API 第 1 版不會影響 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 第 1 版相同，因此無法透過 Reporting API v1 批次處理。因此因為應用程式開發人員開始改用 Reporting API v1，報表數量 相差不遠，但傳送至端點伺服器的要求量會增加。

應用程式開發人員：遷移至 `Reporting-Endpoints` (v1)

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

使用新版 Reporting API (v1) 有幾項好處 ✅：

這是因為瀏覽器信號具有正面影響第 1 版仍可支援跨瀏覽器，但第 1 版和 v0 不同 Edge)。
它的 API 設計更精簡
工具正針對新的 Reporting API (v1) 開發中。

請留意以下事項：

如果您的網站已使用包含 Report-To 標頭的 Reporting API v0，請遷移至 Reporting API v1 (請參閱遷移步驟)。如果您的網站已在使用檢舉功能違反《內容政策》規定，請參閱 CSP 報告遷移步驟。
如果您的網站尚未使用 Reporting API，而您將新增報表功能：請使用新的 Reporting API (v1) (Reporting-Endpoints 標頭)。這有一個例外情況 this：如需使用網路錯誤記錄，請使用 Report-To (v0)。網路錯誤記錄 Reporting API v1 目前不支援的功能。新的網路錯誤記錄機制而在可用之前，請使用 Reporting API 第 0 版。如需網路錯誤記錄功能除了其他報表類型，請同時使用 Report-To (v0) 和 Reporting-Endpoints (v1)。v0 提供網路錯誤記錄，v1 則提供所有其他類型的報告。

遷移步驟

這項遷移作業的目標，是不會遺失您之前取得 v0 報表。

步驟 1 (現在)：同時使用以下兩種標頭：Report-To (v0) 和 Reporting-Endpoints (v1)。

有了這項功能，您就能：
- 新版 Chrome 和 Edge 用戶端提供報告，都要歸功於 Reporting-Endpoints (v1)。
- Report-To (v0) 提供舊版 Chrome 和 Edge 用戶端的報告。
支援 Reporting-Endpoints 的瀏覽器執行個體將使用 Reporting-Endpoints，以及不會改回使用 Report-To 的執行個體。請求和報表的格式相同第 0 版和第 1 版
步驟 2 (現在進行)：確保針對符合以下條件的所有回應設定 Reporting-Endpoints 標頭產生報表

使用第 0 版時，您可以選擇只針對部分回應和其他文件設定回報端點該來源上的 (頁) 會使用這個「微光模式」端點使用第 1 版時，由於限定範圍，您必須針對所有可能產生的回應設定 Reporting-Endpoints 標頭報表。
步驟 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 報表」正確做法「不」使用 Reporting API。
使用 Reporting API 時，請使用 Report-To 標頭 (舊版) 或新版 Reporting-Endpoints (第 1 版)。僅支援 Chrome 和 Edge。報表請求格式與其他 Reporting API 要求相同，以及相同的內容類型 application/reports+json。

我們不建議採用第一種方法 (僅使用 report-uri)，採用第二種方法有幾項好處。具體而言，這項工具可讓您在單一介面中設定所有報表類型的報表，以及設定一般端點 (因為所有透過 Reporting API 產生的報表要求，以及其他報表要求的格式 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 (立即執行)：如果您尚未新增，report-to請在report-uri旁邊新增。僅支援 report-uri (Firefox) 的瀏覽器會使用 report-uri 和支援此功能的瀏覽器支援 report-to(Chrome、Edge) 將使用 report-to。如要指定您要使用的已命名端點在 report-to 中，請同時使用標頭 Report-To 和 Reporting-Endpoints。這可確保您。
步驟 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 (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 後，程式碼就會如下所示。

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

觀察所有頁面

舊版程式碼 (包含 v0)，例如 Express

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

使用第 0 版時，您只能針對部分回應設定回報端點。其他該來源上的文件 (頁面) 會自動使用這些環境端點。這裡的端點 "/" 的值會用於所有回應，例如 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 已不再建議。如果程式碼如上方所示，請進行遷移。請見下方的「新程式碼範例」(綠色)。

使用 report-uri 和 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。但為了顧及回溯相容性，該 API 仍會保留 report-uri。數個瀏覽器不支援 report-to敬上但支援 report-uri。

不過，這可能還是更好：這個程式碼使用的是 Reporting API v0 (Report-To 標頭)。遷移至 v1：請參閱「新代碼」範例 (綠色)。

新程式碼，搭配 report-uri 和 report-to 指令，其中含有 Reporting-Endpoint (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。