Reporting API 已推出新版本。安全更有保障,且可能跨瀏覽器支援。
Reporting API 會在訪客使用網站時通知您,這提供了 瞭解瀏覽器介入措施、瀏覽器異常終止、違反《Content-Security-Policy》違規事項, COOP/COEP 違規、淘汰警告等
Reporting API 已推出新版本。新 API 不僅精簡, 。
摘要
網站開發人員
如果網站已有報表功能:請使用新標題遷移至第 1 版
(Reporting-Endpoints
),但保留舊版標頭一段時間 (Report-To
)。
請參閱遷移:程式碼範例。
如果要在網站上加入報表功能:請只使用新標題
(Reporting-Endpoints
)。
⚠️ 這兩種情況下,請務必針對可能出現的所有回應設定 Reporting-Endpoints
標頭
產生報表。
報表服務開發人員
如果您維護端點服務或自行營運,則預期流量會隨著您
或外部開發人員遷移至 Reporting API v1 (Reporting-Endpoints
標題)。
請繼續閱讀下方的詳細資訊和範例程式碼!
網路錯誤記錄
即將開發網路錯誤記錄的新機制。待更新發布後,從 Reporting API 第 0 版改用這個新機制。
示範和代碼
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
{0 會使用 Report-To
標頭設定已命名的端點群組,其他標頭中的 report-to
指令則可參照這些端點群組。
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
指令來參照這些端點群組。
- 報表範圍不同,
使用第 0 版時,您只能針對部分回應設定回報端點。該文件中的其他文件 (頁面) 來源會自動使用這些環境端點
使用 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 產生的報表類型 |
|
未變更,除了網路錯誤記錄 (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 版- 新版 Chrome 和 Edge 用戶端提供報告,都要歸功於
步驟 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)。
基本遷移
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" }] }
如果網站已有報表功能,請僅暫時保留 Report-To
(在大部分 Chrome 和 Edge 用戶端完成更新前),以免遺失報告。
如需網路錯誤記錄,請保留 Report-To
,直到網路錯誤記錄功能更換為止
可供使用。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
在大部分 Chrome 和 Edge 用戶端完成更新並支援 API v1 後,程式碼就會如下所示。
請注意,使用第 1 版時,您還是可以將特定的報表類型傳送至特定端點。但你 每個端點只能有一個網址。
觀察所有頁面
app.get("/", (request, response) => { response.set("Report-To", …) response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
使用第 0 版時,您只能針對部分回應設定回報端點。其他
該來源上的文件 (頁面) 會自動使用這些環境端點。這裡的端點
"/"
的值會用於所有回應,例如 page1
。
// 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 報告遷移
Content-Security-Policy: ...; report-uri https://reports.example/main
只使用 report-uri
已不再
建議。
如果程式碼如上方所示,請進行遷移。請見下方的「新程式碼範例」(綠色)。
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:請參閱
「新代碼」範例 (綠色)。
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 (v1)
主頁橫幅由 Nine Koepfer / @enka80 提供 Unsplash 編輯完畢。感謝 Ian Clelland、Eiji Kitamura 和 Milica Mihajlija 分享相關評論和建議 一文。