Trang này được dịch bởi Cloud Translation API.

Chuyển sang API Báo cáo phiên bản 1

Hiện đã có phiên bản mới của API Báo cáo. Tính năng này riêng tư hơn và có nhiều khả năng được hỗ trợ trên nhiều trình duyệt hơn.

Maud Nalpas

API báo cáo thông báo cho bạn về các lỗi xảy ra trên trang web của bạn khi khách truy cập sử dụng trang web đó. Công cụ này cung cấp cho bạn thông tin về các biện pháp can thiệp vào trình duyệt, sự cố trình duyệt, lỗi vi phạm Chính sách bảo mật nội dung, lỗi vi phạm COOP/COEP, cảnh báo về việc ngừng sử dụng và nhiều thông tin khác.

Hiện đã có phiên bản mới của API Báo cáo. API mới tinh gọn hơn và có nhiều khả năng sẽ được hỗ trợ trên các trình duyệt.

Tóm tắt

Nhà phát triển trang web

Nếu bạn đã có chức năng báo cáo cho trang web của mình: Hãy di chuyển sang phiên bản 1 bằng cách sử dụng tiêu đề mới (Reporting-Endpoints), nhưng hãy giữ lại tiêu đề cũ trong một thời gian (Report-To). Xem nội dung Di chuyển: mã mẫu.

Nếu bạn vừa mới thêm chức năng báo cáo vào trang web của mình: hãy chỉ sử dụng tiêu đề mới (Reporting-Endpoints).

⚠️ Trong cả hai trường hợp, hãy nhớ đặt tiêu đề Reporting-Endpoints trên tất cả phản hồi có thể tạo báo cáo.

Nhà phát triển dịch vụ báo cáo

Nếu bạn đang duy trì một dịch vụ thiết bị đầu cuối hoặc đang tự vận hành, hãy chờ đợi nhiều lưu lượng truy cập hơn khi bạn hoặc các nhà phát triển bên ngoài chuyển sang API Báo cáo phiên bản 1 (tiêu đề Reporting-Endpoints).

Hãy đọc tiếp để biết chi tiết và mã ví dụ!

Ghi nhật ký lỗi mạng

Thận trọng: Nếu bạn sử dụng tính năng Ghi nhật ký lỗi mạng, hãy tiếp tục sử dụng Report-To (v0) vì tính năng Ghi nhật ký lỗi mạng không được hỗ trợ trong API Báo cáo phiên bản 1.

Chúng tôi sẽ phát triển một cơ chế mới cho tính năng Ghi nhật ký lỗi mạng. Khi có sẵn, hãy chuyển từ API Báo cáo phiên bản 0 sang cơ chế mới đó.

Bản minh hoạ và mã

Trang web minh hoạ: API báo cáo mới (phiên bản 1)
Mã cho trang web minh hoạ

Sự khác biệt giữa phiên bản 0 và phiên bản 1

Nội dung thay đổi

Nền tảng API thì khác.

phiên bản 0 (cũ)

 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 sử dụng tiêu đề Report-To để định cấu hình nhóm điểm cuối được đặt tên và lệnh report-to trong các tiêu đề khác để tham chiếu đến các nhóm điểm cuối này.

phiên bản 1 (mới)

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

v1 sử dụng tiêu đề Reporting-Endpoints để định cấu hình điểm cuối được đặt tên. Giống như v0, phương thức này sử dụng lệnh report-to trong các tiêu đề khác để tham chiếu đến các nhóm điểm cuối này.

Phạm vi của báo cáo này sẽ khác nhau.

phiên bản 0 (cũ)

Với phiên bản 0, bạn chỉ có thể thiết lập điểm cuối báo cáo trên một số phản hồi. Các tài liệu (trang) khác trên nguồn gốc đó sẽ tự động sử dụng các điểm cuối môi trường xung quanh này.

phiên bản 1 (mới)

Với v1, bạn cần đặt tiêu đề Reporting-Endpoints trên mọi phản hồi có thể tạo báo cáo.

Cả hai API đều hỗ trợ cùng một loại báo cáo, nhưng có một ngoại lệ là phiên bản 1 không hỗ trợ Báo cáo lỗi mạng. Hãy đọc thêm trong các bước di chuyển.
v0 chưa và sẽ không được hỗ trợ trên các trình duyệt. v1 có nhiều khả năng sẽ được hỗ trợ trên nhiều trình duyệt trong tương lai.

Những nội dung không thay đổi

Định dạng và cấu trúc của báo cáo không thay đổi.
Yêu cầu do trình duyệt gửi đến điểm cuối vẫn là yêu cầu POST của Content-type application/reports+json.
Việc liên kết một số điểm cuối đến một số loại báo cáo nhất định được hỗ trợ trong cả phiên bản 0 và phiên bản 1.
Vai trò của điểm cuối default không thay đổi.
API Báo cáo phiên bản 1 không ảnh hưởng đến ReportingObserver. ReportingObserver tiếp tục có quyền truy cập vào tất cả các báo cáo có thể ghi nhận được và có định dạng giống nhau.

Tất cả sự khác biệt giữa v0 và v1

	API Báo cáo cũ (v0) tiêu đề `Report-To`	API Báo cáo mới (v1) tiêu đề `Reporting-Endpoints`
Hỗ trợ trình duyệt	Chrome 69 trở lên và Edge 69 trở lên.	Chrome 96 trở lên và Edge 96 trở lên. Firefox có hỗ trợ. Safari không phản đối. Xem tín hiệu của trình duyệt.
Thiết bị đầu cuối	Gửi báo cáo đến bất kỳ người thu thập báo cáo nào trong số nhiều trình thu thập báo cáo (nhiều URL được xác định cho mỗi nhóm điểm cuối).	Gửi báo cáo đến người thu thập báo cáo cụ thể (chỉ một URL được xác định cho mỗi điểm cuối).
Nền tảng API	Sử dụng tiêu đề `Report-To` để định cấu hình các nhóm điểm cuối được đặt tên.	Sử dụng tiêu đề `Reporting-Endpoints` để định cấu hình điểm cuối được đặt tên.
Các loại báo cáo có thể được tạo thông qua API này	Ngừng sử dụng Can thiệp Vụ đụng xe COOP/COEP Chính sách bảo mật nội dung cấp 3 (CSP cấp 3) Ghi nhật ký lỗi mạng (NEL) _{Tìm hiểu thêm về các loại báo cáo trong bài đăng về API Báo cáo.}	Không thay đổi, ngoại trừ tính năng Ghi nhật ký lỗi mạng (NEL): tính năng này không được hỗ trợ trong API Báo cáo mới (v1).
Phạm vi báo cáo	Nguồn gốc từ bạn. Tiêu đề `Report-To` của một tài liệu ảnh hưởng đến các tài liệu (trang) khác trong nguồn gốc đó. Trường `url` của báo cáo vẫn thay đổi theo từng tài liệu.	Tài liệu. Tiêu đề `Reporting-Endpoints` của tài liệu chỉ ảnh hưởng đến tài liệu đó. Trường `url` của báo cáo vẫn thay đổi theo từng tài liệu.
Tách biệt báo cáo (phân lô)	Nhiều tài liệu (trang) hoặc trang web/nguồn gốc tạo báo cáo cùng một lúc và có cùng điểm cuối báo cáo sẽ được nhóm lại với nhau: chúng sẽ được gửi trong cùng một thông báo đến điểm cuối báo cáo.	Báo cáo từ các tài liệu (trang) khác nhau không bao giờ được gửi cùng nhau. Ngay cả khi hai tài liệu (trang) thuộc cùng một nguồn gốc tạo một báo cáo cùng một lúc, cho cùng một điểm cuối, các báo cáo này sẽ không được phân thành lô. Đây là một cơ chế để giảm thiểu các cuộc tấn công về quyền riêng tư. Các báo cáo thuộc cùng một tài liệu (trang) có thể được gửi cùng nhau.
Hỗ trợ cân bằng tải / mức độ ưu tiên	Có	Không

Nhà phát triển thiết bị đầu cuối: Dự kiến có nhiều lưu lượng truy cập hơn

Nếu bạn đã thiết lập máy chủ của riêng mình làm điểm cuối báo cáo hoặc nếu bạn đang phát triển hoặc duy trì trình thu thập báo cáo dưới dạng dịch vụ, hãy kỳ vọng có nhiều lưu lượng truy cập hơn đến điểm cuối đó.

Điều này là do các báo cáo không được phân theo lô với API Báo cáo phiên bản 1 như với API Báo cáo phiên bản 0. Do đó, khi các nhà phát triển ứng dụng bắt đầu chuyển sang API Báo cáo phiên bản 1, số lượng báo cáo sẽ vẫn giữ nguyên, nhưng lượng yêu cầu đến máy chủ điểm cuối sẽ tăng lên.

Nhà phát triển ứng dụng: Di chuyển sang `Reporting-Endpoints` (phiên bản 1)

Bạn nên làm gì?

Việc sử dụng API Báo cáo mới (v1) mới có một số lợi ích ✅:

Tín hiệu của trình duyệt tích cực, có nghĩa là phiên bản 1 có thể được hỗ trợ trên nhiều trình duyệt (không giống như phiên bản 0 chỉ được hỗ trợ trong Chrome và Edge).
API tinh gọn hơn.
Công cụ đang được phát triển xoay quanh API Báo cáo mới (v1).

Lưu ý như sau:

Nếu trang web của bạn đã sử dụng API Báo cáo phiên bản 0 với tiêu đề Report-To, hãy chuyển sang API Báo cáo phiên bản 1 (xem các bước di chuyển). Nếu trang web của bạn đã sử dụng chức năng báo cáo đối với các lỗi vi phạm Chính sách bảo mật nội dung, hãy xem các bước di chuyển cụ thể để có báo cáo CSP.
Nếu trang web của bạn chưa sử dụng API Báo cáo và bạn hiện đang thêm chức năng báo cáo: hãy sử dụng API Báo cáo mới (v1) (tiêu đề Reporting-Endpoints). Có một ngoại lệ cho điều này: nếu bạn cần sử dụng tính năng Ghi nhật ký lỗi mạng, hãy dùng Report-To (v0). API Báo cáo phiên bản 1 hiện không hỗ trợ tính năng Ghi nhật ký lỗi mạng. Chúng tôi sẽ phát triển một cơ chế mới cho tính năng Ghi nhật ký lỗi mạng⏤cho đến khi có sẵn, hãy sử dụng API Báo cáo phiên bản 0. Nếu bạn cần Ghi nhật ký lỗi mạng cùng với các loại báo cáo khác, hãy sử dụng cả Report-To (v0) và Reporting-Endpoints (v1). v0 cung cấp cho bạn tính năng Ghi nhật ký lỗi mạng, còn v1 cung cấp cho bạn báo cáo về tất cả các loại khác.

Các bước di chuyển

Mục tiêu của bạn trong quá trình di chuyển này là không bị mất các báo cáo mà bạn từng nhận được với phiên bản 0.

Bước 1 (làm ngay bây giờ): Sử dụng cả hai tiêu đề: Report-To (v0) và Reporting-Endpoints (v1).

Với gói này, bạn sẽ có:
- Báo cáo từ các ứng dụng Chrome và Edge mới hơn nhờ có Reporting-Endpoints (v1).
- Báo cáo từ các ứng dụng Chrome và Edge cũ hơn nhờ có Report-To (v0).
Các phiên bản trình duyệt hỗ trợ Reporting-Endpoints sẽ sử dụng Reporting-Endpoints và các phiên bản không hỗ trợ Report-To. Định dạng yêu cầu và báo cáo là giống nhau đối với phiên bản 0 và phiên bản 1.
Bước 2 (làm ngay): Đảm bảo rằng bạn đã đặt tiêu đề Reporting-Endpoints trên tất cả phản hồi có thể tạo báo cáo.

Với v0, bạn có thể chọn chỉ thiết lập điểm cuối báo cáo trên một số phản hồi và các tài liệu khác (các trang) trên nguồn gốc đó sẽ sử dụng điểm cuối "môi trường" này. Với v1, do sự khác biệt về phạm vi, bạn cần đặt tiêu đề Reporting-Endpoints trên tất cả phản hồi có thể tạo báo cáo.
Bước 3 (bắt đầu sau): Sau khi tất cả hoặc hầu hết người dùng cập nhật lên phiên bản Chrome hoặc Edge mới hơn (phiên bản 96 trở lên), hãy xoá Report-To (v0) và chỉ giữ lại Reporting-Endpoints.

Một ngoại lệ: nếu bạn cần báo cáo Ghi nhật ký lỗi mạng, hãy giữ lại Report-To cho đến khi triển khai cơ chế mới cho tính năng Ghi nhật ký lỗi mạng.

Xem các ví dụ về mã trong sổ tay nấu ăn di chuyển.

Các bước di chuyển cho tính năng báo cáo CSP

Có 2 cách để định cấu hình báo cáo vi phạm Chính sách bảo mật nội dung:

Chỉ riêng tiêu đề CSP thông qua lệnh report-uri. Trình duyệt này được hỗ trợ trên nhiều trình duyệt, trên Chrome, Firefox, Safari và Edge. Báo cáo được gửi với loại nội dung application/csp-report và có định dạng dành riêng cho CSP. Những báo cáo này được gọi là "Báo cáo CSP cấp 2" và không dựa vào API Báo cáo.
Với API Báo cáo, hoạt động đó được thực hiện qua tiêu đề Report-To (cũ) hoặc Reporting-Endpoints mới hơn (v1). Tính năng này chỉ được hỗ trợ trong Chrome và Edge. Yêu cầu báo cáo có cùng định dạng với các yêu cầu API Báo cáo khác và có cùng loại nội dung application/reports+json.

Phương pháp đầu tiên (chỉ report-uri) không còn được khuyên dùng và việc sử dụng phương pháp thứ hai có một số lợi ích. Cụ thể, tính năng này cho phép bạn sử dụng một cách duy nhất để thiết lập báo cáo cho tất cả các loại báo cáo cũng như thiết lập điểm cuối chung (vì tất cả các yêu cầu báo cáo được tạo qua API Báo cáo⏤CSP và các yêu cầu khác⏤có cùng định dạng application/reports+json.

Tuy nhiên, chỉ một số trình duyệt hỗ trợ report-to. Do đó, bạn nên giữ report-uri cùng với phương pháp API Báo cáo (Report-To hoặc tốt hơn là Reporting-Endpoints) để nhận được báo cáo vi phạm CSP từ nhiều trình duyệt. Trong một trình duyệt nhận dạng report-uri và report-to, report-uri sẽ bị bỏ qua nếu có report-to. Trong một trình duyệt chỉ nhận dạng report-uri, thì chỉ report-uri sẽ được xem xét.

Bước 1 (làm ngay): Nếu bạn chưa thêm, hãy thêm report-to cùng với report-uri. Các trình duyệt chỉ hỗ trợ report-uri (Firefox) sẽ sử dụng report-uri, và các trình duyệt cũng hỗ trợ report-to(Chrome, Edge) sẽ sử dụng report-to. Để chỉ định các điểm cuối được đặt tên mà bạn sẽ sử dụng trong report-to, hãy sử dụng cả hai tiêu đề Report-To và Reporting-Endpoints. Điều này đảm bảo rằng bạn nhận được báo cáo từ cả ứng dụng Chrome và Edge mới hơn và cũ.
Bước 3 (bắt đầu sau): Sau khi tất cả hoặc hầu hết người dùng cập nhật lên phiên bản Chrome hoặc Edge mới hơn (phiên bản 96 trở lên), hãy xoá Report-To (v0) và chỉ giữ lại Reporting-Endpoints. Giữ lại report-uri để bạn vẫn nhận được báo cáo cho các trình duyệt chỉ hỗ trợ tiện ích đó.

Xem mã ví dụ cho các bước này trong bài viết di chuyển báo cáo CSP.

Di chuyển: mã ví dụ

Tổng quan

Nếu bạn đang sử dụng API Báo cáo cũ (v0) để nhận báo cáo vi phạm đối với COOP (tiêu đề Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy) hoặc chính sách tài liệu (tiêu đề Document-Policy): bạn không cần tự thay đổi các tiêu đề chính sách này khi di chuyển sang API Báo cáo phiên bản 1. Bạn cần di chuyển từ tiêu đề Report-To cũ sang tiêu đề Reporting-Endpoints mới.

Nếu đang sử dụng API Báo cáo cũ (v0) để nhận báo cáo vi phạm cho CSP (tiêu đề Content-Security-Policy), thì bạn có thể phải điều chỉnh Content-Security-Policy trong quá trình di chuyển sang API Báo cáo mới (v1).

Di chuyển cơ bản

Mã cũ (với phiên bản 0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Mã mới (mã chuyển đổi với v0 cùng với 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" }] }

Nếu bạn đã có chức năng báo cáo trên trang web của mình, hãy chỉ tạm thời giữ lại Report-To (cho đến khi hầu hết các ứng dụng của Chrome và Edge được cập nhật) để tránh bị mất báo cáo.

Nếu bạn cần Ghi nhật ký lỗi mạng, hãy giữ lại Report-To cho đến khi tính năng thay thế tính năng Ghi nhật ký lỗi mạng có sẵn.

Mã mới (chỉ với phiên bản 1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Đây là giao diện mã của bạn trong tương lai, sau khi hầu hết các ứng dụng Chrome và Edge đã được cập nhật và hỗ trợ API phiên bản 1.

Xin lưu ý rằng với phiên bản 1, bạn vẫn có thể gửi các loại báo cáo cụ thể đến các điểm cuối cụ thể. Tuy nhiên, bạn chỉ được có một URL cho mỗi điểm cuối.

Quan sát tất cả các trang

Mã cũ (với phiên bản 0), ví dụ: với Express

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

Với phiên bản 0, bạn chỉ có thể thiết lập điểm cuối báo cáo trên một số phản hồi. Các tài liệu (trang) khác trên nguồn gốc đó sẽ tự động sử dụng các điểm cuối môi trường xung quanh này. Ở đây, các điểm cuối được đặt cho "/" được sử dụng cho mọi phản hồi, chẳng hạn như cho page1.

Mã mới (với phiên bản 1), ví dụ: với 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(...)
});

Với v1, bạn cần đặt tiêu đề Reporting-Endpoints trên tất cả các phản hồi có thể tạo báo cáo.

Di chuyển báo cáo CSP

Mã cũ, chỉ có URI báo cáo

Content-Security-Policy: ...; report-uri https://reports.example/main

Bạn không nên chỉ sử dụng report-uri. Nếu mã của bạn giống như trên, hãy di chuyển. Xem các ví dụ về Mã mới bên dưới (màu xanh lục).

Mã cũ tốt hơn, với URI report-uri và lệnh report-to có tiêu đề Report-To (v0)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Cách này hiệu quả hơn: mã này sử dụng report-to, phiên bản thay thế mới hơn cho report-uri. Trình duyệt này vẫn giữ lại URI báo cáo để đảm bảo khả năng tương thích ngược. Một số trình duyệt không hỗ trợ report-to nhưng vẫn hỗ trợ report-uri.

Tuy nhiên, cách này có thể tốt hơn: mã này sử dụng API Báo cáo phiên bản 0 (tiêu đề Report-To). Chuyển sang phiên bản 1: hãy xem các ví dụ về "Mã mới" bên dưới (màu xanh lục).

Mã mới, có report-uri và lệnh report-to với tiêu đề 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: ...

Giữ lệnh report-uri cùng với lệnh report-to cho đến khi lệnh report-to được hỗ trợ trên các trình duyệt. Xem bảng tương thích với trình duyệt.

Tạm thời giữ Report-To cùng với Reporting-Endpoints. Khi hầu hết khách truy cập Chrome và Edge đã nâng cấp lên phiên bản trình duyệt hơn 96, hãy xoá Report-To.

Tài liệu đọc thêm

Giám sát ứng dụng web của bạn bằng API Báo cáo (bài đăng chính về API Báo cáo)
Quy cách: API Báo cáo cũ (v0)
Quy cách: API Báo cáo mới (v1)

Hình ảnh chính của Nine Koepfer / @enka80 trên Unsplash, đã chỉnh sửa. Cảm ơn Ian Cllelland, Eiji Kitamura và Milica Mihajlija đã viết rất nhiều bài đánh giá và đề xuất về bài viết này.