迁移到 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 标头）时，预计流量会增加。

请继续阅读，了解详情和示例代码！

网络错误日志记录

注意：如果您使用网络错误日志记录，请继续使用 Report-To (v0)，因为 Reporting API v1 不支持网络错误日志记录。

我们将开发一种新的网络错误日志记录机制。一旦该机制可用，请从 Reporting API v0 切换到该新机制。

演示和代码

演示网站：新的 Reporting API (v1)
演示网站的代码

v0 和 v1 之间的区别

具体变化

API Surface 不同。

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 标头来配置命名端点。与 v0 一样，它使用其他标头中的 report-to 指令来引用这些端点组。

报告的范围不同。

v0（旧版）

在 v0 中，您可以仅针对部分回答设置举报端点。相应来源上的其他文档（网页）会自动使用这些环境端点。

v1（新）

在 v1 中，您需要在可能会生成报告的所有响应中设置 Reporting-Endpoints 标头。

这两个 API 支持相同的报告类型，但有一个例外：v1 不支持网络错误报告。如需了解详情，请参阅迁移步骤。
v0 在浏览器中不受支持，未来也不会受支持。v1 未来更有可能在多个浏览器中受支持。

保持不变的方面

报告的格式和结构保持不变。
浏览器发送到端点的请求仍然是 Content-type application/reports+json 的 POST 请求。
v0 和 v1 都支持将某些端点映射到某些报告类型。
default 端点的角色保持不变。
Reporting API v1 对 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 Surface	使用 `Report-To` 标头配置命名端点组。	使用 `Reporting-Endpoints` 标头配置命名端点。
可通过此 API 生成的报告类型	弃用干预交通事故 COOP/COEP 内容安全政策第 3 级 (CSP 第 3 级) 网络错误日志记录 (NEL) _{如需详细了解报告类型，请参阅有关 Reporting API 的帖子。}	未发生变化，但网络错误日志记录 (NEL)：新版 Reporting API (v1) 不支持此功能。
报告范围	源网域的技术。文档的 `Report-To` 标头会影响来自相应来源的其他文档（网页）。报告的 `url` 字段仍然因文档而异。	Document. 文档的 `Reporting-Endpoints` 标题只会影响该文档。报告的 `url` 字段仍然因文档而异。
报告隔离（批处理）	在同一时间生成报告且具有相同报告端点的不同文档（网页）或网站/来源将一起批处理：它们将通过同一消息发送到报告端点。	来自不同文档（网页）的报告绝不会一起发送。即使来自同一来源的两个文档（网页）同时针对同一端点生成报告，这些报告也不会进行批处理。这是一种用于缓解隐私攻击的机制。来自同一文档（网页）的报告可能会一起发送。
支持负载均衡 / 优先级	是	否

端点开发者：预计流量会增加

如果您已将自己的服务器设置为报告端点，或者您正在开发或维护作为服务的报告收集器，则预计该端点的流量会增加。

这是因为 Reporting API v1 不像 Reporting API v0 那样对报告进行批处理。因此，随着应用开发者开始迁移到 Reporting API v1，报告数量将保持相似，但对端点服务器的请求量会增加。

应用开发者：迁移到 `Reporting-Endpoints` (v1)

您该怎么做？

使用新的 Reporting API (v1) 有以下几个好处 ✅：

浏览器信号是积极的，这意味着 v1 可以跨浏览器使用（与仅在 Chrome 和 Edge 中受支持的 v0 不同）。
API 更精简。
我们正在围绕新的 Reporting API (v1) 开发工具。

了解了这一点：

如果您的网站已使用带有 Report-To 标头的 Reporting API v0，请迁移到 Reporting API v1（请参阅迁移步骤）。如果您的网站已使用内容安全政策违规行为的报告功能，请查看 CSP 报告的具体迁移步骤。
如果您的网站尚未使用 Reporting API，但现在要添加报告功能：请使用新版 Reporting API (v1)（Reporting-Endpoints 标题）。不过，有一个例外情况：如果您需要使用网络错误日志记录，请使用 Report-To (v0)。Reporting API v1 目前不支持网络错误日志记录。将开发一种新的网络错误日志记录机制，在此机制可用之前，请使用 Reporting API v0。如果您需要同时使用网络错误日志记录和其他报告类型，请同时使用 Report-To (v0) 和 Reporting-Endpoints (v1)。v0 可提供网络错误日志记录，而 v1 可提供所有其他类型的报告。

迁移步骤

此次迁移的目标是不丢失您之前通过 v0 获取的报告。

第 1 步（立即执行）：同时使用 Report-To (v0) 和 Reporting-Endpoints (v1) 这两个标头。

这样一来，您就可以：
- 得益于 Reporting-Endpoints (v1)，新版 Chrome 和 Edge 客户端的报告。
- 来自旧版 Chrome 和 Edge 客户端的报告（归功于 Report-To [v0]）。
支持 Reporting-Endpoints 的浏览器实例将使用 Reporting-Endpoints，不支持 Reporting-Endpoints 的实例将回退到 Report-To。v0 和 v1 的请求和报告格式相同。
第 2 步（立即执行）：确保在所有可能会生成报告的响应中设置 Reporting-Endpoints 标头。

在 v0 中，您可以选择仅在某些响应中设置报告端点，而相应来源上的其他文档（网页）将使用此“环境”端点。在 v1 中，由于作用域不同，您需要在可能会生成报告的所有响应中设置 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 Level 2 Reports”，不依赖于 Reporting 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 步（立即执行）：如果您尚未添加 report-to，请将其与 report-uri 一起添加。仅支持 report-uri (Firefox) 的浏览器将使用 report-uri，同时支持 report-to（Chrome、Edge）的浏览器将使用 report-to。如需在 report-to 中指定要使用的命名端点，请同时使用 Report-To 和 Reporting-Endpoints 这两个标头。这样可确保您获得来自旧版和新版 Chrome 及 Edge 客户端的报告。
第 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 标头）的违规报告，则可能需要在迁移到新版 Reporting API (v1) 的过程中调整 Content-Security-Policy。

基本迁移

旧版代码（含 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。如果您的代码如上所示，请进行迁移。请参阅下方的“新代码示例”（以绿色显示）。

更好的旧版代码，包含 report-uri 和带有 Report-To (v0) 标头的 report-to 指令

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 和带有 Reporting-Endpoints (v1) 标头的 report-to 指令

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 监控 Web 应用（有关 Reporting API 的主要博文）
规范：旧版 Reporting API (v0)
规范：新的 Reporting API (v1)

非常感谢 Ian Clelland、Eiji Kitamura 和 Milica Mihajlija 对本文的审核和建议。