迁移到 Reporting API v1

Reporting API 已推出新版本。它具有更高的私密性，更有可能在各个浏览器上受支持。

Maud Nalpas
Maud Nalpas
X GitHub

当访问者使用您的网站时，Reporting API 会通知您。它提供 了解浏览器干预、浏览器崩溃、内容安全政策 COOP/COEP 违规、弃用警告等。

Reporting API 已推出新版本。新 API 更精简， 对各种浏览器的支持。

摘要

网站开发者

如果您的网站已有报告功能：请使用新标头迁移到 v1 (Reporting-Endpoints)，但将旧版标头保留一段时间 (Report-To)。 请参阅迁移：示例代码。

如果您刚刚向网站添加报告功能：请仅使用新的标题 （Reporting-Endpoints）。

⚠️ 在这两种情况下，请务必在所有可能响应的响应中设置 Reporting-Endpoints 标头 生成报告。

报告服务开发者

如果您要维护端点服务或运营自己的端点服务，预计会出现更多流量，因为 或外部开发者迁移到 Reporting API v1（Reporting-Endpoints 标头）。

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

网络错误日志记录

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

演示和代码

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

  • 此报告的范围有所不同。
v0（旧版）

使用 v0 时，您只能为某些响应设置报告端点。有关该组织的其他文档（页面） 来源会自动使用这些 Ambient 端点。

v1（新功能）

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

  • 两个 API 支持相同的报告类型，但有一个例外：v1 不支持网络错误报告。如需了解详情，请参阅迁移步骤。
  • v0 目前不受所有浏览器支持，以后也不会受到支持。版本 1 更有可能在 支持多种浏览器

保持不变的方面

  • 报告的格式和结构保持不变。
  • 浏览器向端点发送的请求仍为 Content-type 的 POST 请求 application/reports+json。
  • 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` 标头配置已命名的 endpoints。
可通过此 API 生成的报告类型
  • 弃用
  • 干预
  • 崩溃
  • COOP/COEP
  • 内容安全政策级别 3（CSP 级别 3）
  • 网络错误日志记录 (NEL)
。 请在 Reporting 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 预计会实现跨浏览器支持（这与仅 Chrome 浏览器和 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 v0。如果您需要网络错误日志记录 与其他报告类型一起使用，请同时使用 Report-To (v0) 和 Reporting-Endpoints (v1)。v0 网络错误日志记录，而 v1 提供所有其他类型的报告。

迁移步骤

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

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

    这样一来，您就可以：

    • 得益于 Reporting-Endpoints (v1)，较新的 Chrome 和 Edge 客户端能够提供报告。
    • 旧版 Chrome 和 Edge 客户端可通过 Report-To (v0) 提供的报告获取服务。

    支持 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有两种方法 违规报告：

  • 通过 report-uri 指令单独使用 CSP 标头。它支持广泛的浏览器、 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），使用第二种方法有一些好处。具体而言，借助该 API，您可以使用单一方式为所有报告类型设置报告以及设置通用端点（因为通过 Reporting API ⏤CSP 生成的所有报告请求和其他 ⏤ 均采用相同的格式 application/reports+json。）

但是，只有少数浏览器支持 report-to。 因此，建议您在 Reporting API 方法 (Report-To) 的同时还使用 report-uri 或 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。这可确保您获得 报告。

  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 header)：迁移时，您无需自行更改这些政策标头 升级到 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 后，您的代码将如下所示。

请注意，使用 v1 时，您仍然可以向特定端点发送特定报告类型。但你 每个端点只能有一个网址。

观察所有网页

旧版代码（使用 v0），例如 Express
app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

使用 v0 时，您只能为某些响应设置报告端点。其他 该来源上的文档（网页）会自动使用这些 Ambient 端点。在这里，设置的端点 for "/" 用于所有响应，例如 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-uri。它仍会保留 report-uri，以确保向后兼容；若干 浏览器不支持 report-to 但支持 report-uri。

尽管如此，还是会有改进空间：此代码使用 Reporting API v0（Report-To 标头）。迁移到 v1：请参阅 “新验证码”示例如下（以绿色显示）。

新代码，包含 report-uri 和 report-to 指令，以及报告-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。

深入阅读

主打图片作者：Nine Koepfer / @enka80 Unlaunch，已修改。非常感谢 Ian Clelland、Eiji Kitamura 和 Milica Mihajlija 一文。