迁移到 Reporting API v1

新版 Reporting API 已发布。它更私密，并且更有可能在各浏览器中受支持。

Maud Nalpas

注意：本文介绍了如何迁移到新版 Reporting API (v1)。如果您刚开始接触 Reporting API 或需要详细的使用示例，请改为参阅有关 Reporting API 的主要文章。

Reporting API 会告知您访问者在使用您的网站时发生的错误。借助该工具，您可以了解浏览器干预、浏览器崩溃、内容安全政策 (CSP) 违规、COOP/COEP 违规、废弃警告等问题。

Reporting API 推出了新版本。新 API 更精简，更有可能获得各浏览器的支持。

注意：旧版 Reporting API 名为 Reporting API v0。新版 Reporting API 命名为 Reporting API v1。

摘要

网站开发者

如果您的网站已有报告功能：请使用新标头 (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 Content-Security-Policy 级别 3 (CSP 级别 3) 网络错误日志记录 (NEL) 如需详细了解报告类型，请参阅 Reports API 博文。	除网络错误日志记录 (NEL)：新版 Reporting API (v1) 不支持此功能外，其他均保持不变。
报告范围	源网域的技术。 文档的 Report-To 标头会影响来自该来源的其他文档（页面）。 报告的 url 字段仍因文档而异。	Document. 文档的 Reporting-Endpoints 标头只会影响该文档。 报告的 url 字段仍因文档而异。
报告隔离（批处理）	如果不同的文档（网页）或网站/来源大约在同一时间生成报告且具有相同的报告端点，则会一起批量处理：它们会在同一消息中发送到报告端点。	不同文档（网页）中的报告绝不会一起发送。即使来自同一来源的两个文档（网页）针对同一端点同时生成报告，这些报告也不会批量处理。这是一种用于缓解隐私攻击的机制。 来自同一文档（网页）的报告可能会一起发送。
支持负载均衡 / 优先级	是	否

端点开发者：预计会获得更多流量

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

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

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

您该怎么做？

使用新版 Reporting API (v1) 有诸多优势：✅

• 浏览器信号为正面，这意味着 v1 应该支持跨浏览器（而 v0 仅受 Chrome 和 Edge 支持）。
• 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 v1 目前不支持网络错误日志记录。我们将开发一种新的网络错误日志记录机制。⏤在此之前，请使用 Reporting API v0。如果您需要同时使用网络错误日志记录和其他报告类型，请同时使用 Report-To (v0) 和 Reporting-Endpoints (v1)。v0 可提供网络错误日志记录，v1 可提供所有其他类型的报告。

迁移步骤

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

注意：由于只有 Chrome 和 Edge 支持 Reporting API v0，因此在迁移到 v1 时，您无需关注其他浏览器。不过请注意，我们可能会支持更多浏览器。目前，这些浏览器没有跟踪 bug，但情况可能会发生变化。

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

   这样一来，您可以：

   • 借助 Reporting-Endpoints (v1)，从较新版本的 Chrome 和 Edge 客户端获取报告。
   • 借助 Report-To (v0)，可以生成来自旧版 Chrome 和 Edge 客户端的报告。

   支持 Reporting-Endpoints 的浏览器实例将使用 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 违规报告：

• 仅使用 CSP 标头（通过 report-uri 指令）。此功能在 Chrome、Firefox、Safari 和 Edge 等多种浏览器中受支持。报告采用内容类型 application/csp-report 发送，且采用 CSP 专用格式。这些报告称为“CSP 级别 2 报告”，不依赖于 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. 第 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 标头）违规报告，则在迁移到新版 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 指令以及 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-uri 指令和 report-to 指令，直到所有浏览器都支持 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 对本文的审核和建议。