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

Giám sát ứng dụng web bằng API Báo cáo

Sử dụng API Báo cáo để theo dõi các lỗi vi phạm bảo mật, lệnh gọi API không dùng nữa và nhiều thông tin khác.

Maud Nalpas

Một số lỗi chỉ xảy ra trong môi trường phát hành chính thức. Bạn sẽ không thấy các lỗi này trên máy hoặc trong quá trình phát triển vì người dùng thực, mạng thực và thiết bị thực sẽ thay đổi trò chơi. API Báo cáo giúp phát hiện một số lỗi như lỗi vi phạm bảo mật hoặc các lệnh gọi API không dùng nữa và sắp không dùng nữa trên trang web của bạn, đồng thời truyền các lỗi đó đến một điểm cuối mà bạn đã chỉ định.

Trình theo dõi này cho phép bạn khai báo những gì bạn muốn theo dõi thông qua tiêu đề HTTP và được trình duyệt vận hành.

Việc thiết lập API Báo cáo giúp bạn yên tâm rằng khi người dùng gặp phải các loại lỗi này, bạn sẽ biết để khắc phục.

Bài đăng này đề cập đến những việc API này có thể làm và cách sử dụng. Hãy cùng tìm hiểu kỹ hơn nhé.

Bản minh hoạ và mã

Xem API Báo cáo hoạt động kể từ phiên bản Chrome 96 trở lên (Chrome Beta hoặc Canary, kể từ tháng 10 năm 2021).

Tổng quan

Sơ đồ tóm tắt các bước bên dưới, từ việc tạo báo cáo đến việc nhà phát triển truy cập vào báo cáo — Cách tạo và gửi báo cáo.

Giả sử trang web site.example của bạn có Content-Security-Policy và Document-Policy. Bạn không biết các tính năng này có tác dụng gì? Không sao, bạn vẫn có thể hiểu ví dụ này.

Bạn quyết định theo dõi trang web của mình để biết thời điểm vi phạm các chính sách này, nhưng cũng vì bạn muốn theo dõi các API không dùng nữa hoặc sắp không dùng nữa mà cơ sở mã của bạn có thể đang sử dụng.

Để làm như vậy, bạn định cấu hình tiêu đề Reporting-Endpoints và ánh xạ các tên điểm cuối này thông qua lệnh report-to trong chính sách của mình nếu cần.

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

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

Những việc không mong muốn sẽ xảy ra và một số người dùng của bạn vi phạm các chính sách này.

Ví dụ về trường hợp vi phạm

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js, do index.html tải

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

Trình duyệt sẽ tạo một báo cáo vi phạm CSP, một báo cáo vi phạm Chính sách tài liệu và một báo cáo về việc ngừng sử dụng để ghi lại các vấn đề này.

Sau một khoảng thời gian trễ ngắn (tối đa một phút), trình duyệt sẽ gửi báo cáo đến điểm cuối được định cấu hình cho loại lỗi vi phạm này. Báo cáo do chính trình duyệt gửi ngoài băng tần (không phải do máy chủ hay trang web của bạn).

(Các) thiết bị đầu cuối sẽ nhận được(các) báo cáo này.

Giờ đây, bạn có thể truy cập vào các báo cáo về các điểm cuối này và theo dõi vấn đề xảy ra. Bạn có thể bắt đầu khắc phục sự cố đang ảnh hưởng đến người dùng.

Báo cáo mẫu

{
  "age": 2,
  "body": {
    "blockedURL": "https://site2.example/script.js",
    "disposition": "enforce",
    "documentURL": "https://site.example",
    "effectiveDirective": "script-src-elem",
    "originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
    "referrer": "https://site.example",
    "sample": "",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://site.example",
  "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

Trường hợp sử dụng và loại báo cáo

Bạn có thể định cấu hình API Báo cáo để giúp theo dõi nhiều loại cảnh báo hoặc vấn đề thú vị xảy ra trên trang web của mình:

Loại báo cáo	Ví dụ về một tình huống trong đó báo cáo sẽ được tạo
Vi phạm CSP (Chỉ cấp 3)	Bạn đã thiết lập `Content-Security-Policy` (CSP) trên một trong các trang của mình, nhưng trang đó đang cố tải một tập lệnh mà CSP của bạn không cho phép.
Vi phạm COOP	Bạn đã đặt `Cross-Origin-Opener-Policy` trên một trang, nhưng một cửa sổ có nguồn gốc khác đang cố gắng tương tác trực tiếp với tài liệu.
Vi phạm COEP	Bạn đã đặt `Cross-Origin-Embedder-Policy` trên một trang, nhưng tài liệu đó có một iframe nhiều nguồn gốc chưa chọn tải bằng các tài liệu nhiều nguồn gốc.
Vi phạm chính sách của tài liệu	Trang có chính sách tài liệu ngăn việc sử dụng `document.write`, nhưng một tập lệnh lại cố gắng gọi `document.write`.
Lỗi vi phạm Chính sách về quyền	Trang này có chính sách quyền ngăn chặn việc sử dụng micrô và một tập lệnh yêu cầu đầu vào âm thanh.
Cảnh báo về việc ngừng sử dụng	Trang đang sử dụng một API không dùng nữa hoặc sẽ không dùng nữa; trang gọi API đó trực tiếp hoặc thông qua một tập lệnh cấp cao nhất của bên thứ ba.
Can thiệp	Trang đang cố gắng thực hiện một việc mà trình duyệt quyết định không thực hiện, vì lý do bảo mật, hiệu suất hoặc trải nghiệm người dùng. Ví dụ trong Chrome: trang sử dụng `document.write` trên mạng chậm hoặc gọi `navigator.vibrate` trong một khung trên nhiều nguồn gốc mà người dùng chưa tương tác.
Sự cố	Trình duyệt gặp sự cố khi trang web của bạn đang mở.

Báo cáo

Báo cáo có dạng như thế nào?

Trình duyệt sẽ gửi báo cáo đến điểm cuối mà bạn đã định cấu hình. Phương thức này gửi các yêu cầu có dạng như sau:

POST
Content-Type: application/reports+json

Tải trọng của các yêu cầu này là một danh sách các báo cáo.

Danh sách báo cáo mẫu

[
  {
    "age": 420,
    "body": {
      "columnNumber": 12,
      "disposition": "enforce",
      "lineNumber": 11,
      "message": "Document policy violation: document-write is not allowed in this document.",
      "policyId": "document-write",
      "sourceFile": "https://site.example/script.js"
    },
    "type": "document-policy-violation",
    "url": "https://site.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  },
  {
    "age": 510,
    "body": {
      "blockedURL": "https://site.example/img.jpg",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://dummy.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  }
]

Dưới đây là dữ liệu bạn có thể tìm thấy trong mỗi báo cáo này:

Trường	Mô tả
`age`	Số mili giây giữa dấu thời gian của báo cáo và thời gian hiện tại.
`body`	Dữ liệu báo cáo thực tế, được chuyển đổi tuần tự thành một chuỗi JSON. Các trường có trong `body` của báo cáo được xác định bởi `type` của báo cáo. ⚠️ Báo cáo thuộc nhiều loại có nội dung khác nhau. Để xem nội dung chính xác của từng loại báo cáo, hãy xem điểm cuối báo cáo minh hoạ và làm theo hướng dẫn để tạo báo cáo mẫu.
`type`	Một loại báo cáo, ví dụ: `csp-violation` hoặc `coep`.
`url`	Địa chỉ của tài liệu hoặc trình thực thi mà báo cáo được tạo. Dữ liệu nhạy cảm như tên người dùng, mật khẩu và mảnh sẽ bị xoá khỏi URL này.
`user_agent`	Tiêu đề `User-Agent` của yêu cầu tạo báo cáo.

Báo cáo có thông tin xác thực

Các điểm cuối báo cáo có nguồn gốc giống với trang tạo báo cáo sẽ nhận được thông tin xác thực (cookie) trong các yêu cầu chứa báo cáo.

Thông tin xác thực có thể cung cấp thêm ngữ cảnh hữu ích về báo cáo; ví dụ: liệu tài khoản của một người dùng cụ thể có liên tục kích hoạt lỗi hay không hoặc liệu một trình tự hành động nhất định được thực hiện trên các trang khác có đang kích hoạt báo cáo trên trang này hay không.

Trình duyệt gửi báo cáo khi nào và bằng cách nào?

Báo cáo được phân phối ngoài phạm vi trang web của bạn: trình duyệt sẽ kiểm soát thời điểm gửi báo cáo đến(các) điểm cuối đã định cấu hình. Ngoài ra, bạn cũng không thể kiểm soát thời điểm trình duyệt gửi báo cáo; trình duyệt sẽ tự động thu thập, xếp hàng và gửi báo cáo vào thời điểm thích hợp.

Điều này có nghĩa là bạn sẽ không gặp phải vấn đề gì về hiệu suất khi sử dụng API Báo cáo.

Báo cáo được gửi trễ (tối đa một phút) để tăng khả năng gửi báo cáo theo lô. Điều này giúp tiết kiệm băng thông để tôn trọng kết nối mạng của người dùng, điều này đặc biệt quan trọng trên thiết bị di động. Trình duyệt cũng có thể trì hoãn việc phân phối nếu đang bận xử lý công việc có mức độ ưu tiên cao hơn hoặc nếu người dùng đang sử dụng mạng chậm và/hoặc bị tắc nghẽn tại thời điểm đó.

Vấn đề về cookie của bên thứ ba và bên thứ nhất

Các báo cáo được tạo do lỗi vi phạm hoặc ngừng hoạt động xảy ra trên trang của bạn sẽ được gửi đến(các) điểm cuối mà bạn đã định cấu hình. Điều này bao gồm cả các lỗi vi phạm do tập lệnh của bên thứ ba chạy trên trang của bạn.

Các lỗi vi phạm hoặc ngừng sử dụng xảy ra trong một iframe trên nhiều nguồn gốc được nhúng trong trang của bạn sẽ không được báo cáo cho(các) điểm cuối của bạn (ít nhất là theo mặc định). Một iframe có thể thiết lập báo cáo riêng và thậm chí báo cáo cho dịch vụ báo cáo của trang web (tức là của bên thứ nhất); nhưng điều đó tuỳ thuộc vào trang web được đóng khung. Ngoài ra, xin lưu ý rằng hầu hết các báo cáo chỉ được tạo nếu trang của bạn vi phạm chính sách và chính sách của trang cũng như chính sách của iframe là khác nhau.

Ví dụ về các tính năng không dùng nữa

Nếu bạn thiết lập tiêu đề Reporting-Endpoints trên trang: API không dùng nữa do các tập lệnh bên thứ ba đang chạy trên trang gọi, thì API này sẽ được báo cáo đến điểm cuối. API không dùng nữa được gọi bởi một iframe nhúng trong trang của bạn sẽ không được báo cáo đến điểm cuối. Báo cáo về việc ngừng sử dụng sẽ chỉ được tạo nếu máy chủ iframe đã thiết lập Điểm cuối báo cáo và báo cáo này sẽ được gửi đến bất kỳ điểm cuối nào mà máy chủ của iframe đã thiết lập. — Nếu bạn thiết lập tiêu đề Reporting-Endpoints trên trang: API không dùng nữa do các tập lệnh của bên thứ ba chạy trên trang gọi sẽ được báo cáo đến điểm cuối của bạn. API không dùng nữa được gọi bởi một iframe nhúng trong trang của bạn sẽ không được báo cáo đến điểm cuối. Báo cáo về việc ngừng sử dụng sẽ chỉ được tạo nếu máy chủ iframe đã thiết lập Điểm cuối báo cáo, đồng thời báo cáo này sẽ được gửi đến bất kỳ điểm cuối nào mà máy chủ của iframe đã thiết lập.

Hỗ trợ trình duyệt

Bảng bên dưới tóm tắt khả năng hỗ trợ trình duyệt cho API Báo cáo phiên bản 1, tức là với tiêu đề Reporting-Endpoints. Trình duyệt hỗ trợ API Báo cáo phiên bản 0 (tiêu đề Report-To) là giống nhau, ngoại trừ một loại báo cáo: Tính năng Ghi nhật ký lỗi mạng không được hỗ trợ trong API Báo cáo mới. Hãy đọc hướng dẫn di chuyển để biết thông tin chi tiết.

Loại báo cáo	Chrome	Chrome dành cho iOS	Safari	Firefox	Edge
Vi phạm Chính sách quyền riêng tư (CSP) (Chỉ ở Cấp 3)*	✔ Có	✔ Có	✔ Có	✘ Không	✔ Có
Ghi nhật ký lỗi mạng	✘ Không	✘ Không	✘ Không	✘ Không	✘ Không
Vi phạm COOP/COEP	✔ Có	✘ Không	✔ Có	✘ Không	✔ Có
Tất cả các loại khác: Vi phạm Chính sách về tài liệu, Ngừng sử dụng, Can thiệp, Sự cố	✔ Có	✘ Không	✘ Không	✘ Không	✔ Có

Bảng này chỉ tóm tắt tính năng hỗ trợ cho report-to bằng tiêu đề Reporting-Endpoints mới. Hãy đọc các mẹo di chuyển báo cáo CSP nếu bạn muốn di chuyển sang Reporting-Endpoints.

Sử dụng API Báo cáo

Quyết định nơi gửi báo cáo

Bạn có hai lựa chọn:

Gửi báo cáo đến một dịch vụ thu thập báo cáo hiện có.
Gửi báo cáo cho một trình thu thập báo cáo mà bạn tự xây dựng và vận hành.

Cách 1: Sử dụng dịch vụ thu thập báo cáo hiện có

Sau đây là một số ví dụ về dịch vụ thu thập báo cáo:

Nếu bạn biết giải pháp khác, hãy mở một vấn đề để cho chúng tôi biết. Chúng tôi sẽ cập nhật bài đăng này!

Ngoài giá cả, hãy cân nhắc những điểm sau khi chọn trình thu thập báo cáo: 🧐

Bộ thu thập này có hỗ trợ tất cả các loại báo cáo không? Ví dụ: không phải tất cả các giải pháp điểm cuối báo cáo đều hỗ trợ báo cáo COOP/COEP.
Bạn có cảm thấy thoải mái khi chia sẻ bất kỳ URL nào của ứng dụng với trình thu thập báo cáo của bên thứ ba không? Ngay cả khi trình duyệt xoá thông tin nhạy cảm khỏi các URL này, thông tin nhạy cảm vẫn có thể bị rò rỉ theo cách này. Nếu bạn thấy điều này quá rủi ro đối với ứng dụng của mình, hãy vận hành điểm cuối báo cáo của riêng bạn.

Cách 2: Tạo và vận hành trình thu thập báo cáo của riêng bạn

Việc xây dựng máy chủ nhận báo cáo của riêng bạn không hề đơn giản. Để bắt đầu, bạn có thể phát triển nhánh các mã nguyên mẫu nhẹ của chúng tôi. Ứng dụng này được tạo bằng Express và có thể nhận cũng như hiển thị báo cáo.

Chuyển đến trình thu thập báo cáo tạo sẵn.
Nhấp vào Remix to Edit (Trộn lại để chỉnh sửa) để có thể chỉnh sửa dự án.
Bây giờ, bạn đã có bản sao! Bạn có thể tuỳ chỉnh thư viện này cho mục đích của riêng mình.

Nếu bạn không sử dụng mã nguyên mẫu và đang xây dựng máy chủ của riêng mình từ đầu:

Kiểm tra các yêu cầu POST có Content-Type là application/reports+json để nhận dạng các yêu cầu báo cáo mà trình duyệt gửi đến điểm cuối của bạn.
Nếu điểm cuối của bạn nằm trên một nguồn gốc khác với trang web, hãy đảm bảo điểm cuối đó hỗ trợ yêu cầu kiểm tra trước CORS.

Cách 3: Kết hợp Cách 1 và 2

Bạn có thể muốn một nhà cung cấp cụ thể xử lý một số loại báo cáo, nhưng có giải pháp nội bộ cho các loại báo cáo khác.

Trong trường hợp này, hãy đặt nhiều điểm cuối như sau:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Định cấu hình tiêu đề `Reporting-Endpoints`

Đặt tiêu đề phản hồi Reporting-Endpoints. Giá trị của thuộc tính này phải là một hoặc một loạt các cặp khoá-giá trị được phân tách bằng dấu phẩy:

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

Nếu đang di chuyển từ API Báo cáo cũ sang API Báo cáo mới, thì bạn nên đặt cả Reporting-Endpoints và Report-To. Xem thông tin chi tiết trong hướng dẫn di chuyển. Cụ thể, nếu bạn chỉ sử dụng tính năng báo cáo lỗi vi phạm Content-Security-Policy thông qua lệnh report-uri, hãy xem các bước di chuyển để báo cáo CSP.

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

Khoá (tên điểm cuối)

Mỗi khoá có thể là một tên do bạn chọn, chẳng hạn như main-endpoint hoặc endpoint-1. Bạn có thể quyết định đặt các điểm cuối được đặt tên khác nhau cho các loại báo cáo khác nhau, ví dụ: my-coop-endpoint, my-csp-endpoint. Nhờ đó, bạn có thể định tuyến báo cáo đến các điểm cuối khác nhau tuỳ thuộc vào loại báo cáo.

Nếu bạn muốn nhận báo cáo can thiệp, ngừng sử dụng và/hoặc sự cố, hãy đặt một điểm cuối có tên là default.

Nếu tiêu đề Reporting-Endpoints không xác định điểm cuối default, thì báo cáo thuộc loại này sẽ không được gửi (mặc dù báo cáo sẽ được tạo).

Lưu ý quan trọng: Mặc dù có tên như vậy, nhưng default không phải là điểm cuối dự phòng. Ví dụ: nếu bạn thiết lập report-to my-endpoint cho Document-Policy và bỏ qua việc xác định my-endpoint trong Reporting-Endpoints, thì báo cáo vi phạm Document-Policy sẽ được tạo nhưng không được gửi vì trình duyệt không biết gửi báo cáo đến đâu.

Giá trị (URL)

Mỗi giá trị là một URL mà bạn chọn để gửi báo cáo. URL cần đặt tại đây phụ thuộc vào quyết định của bạn ở Bước 1.

URL điểm cuối:

Phải bắt đầu bằng dấu gạch chéo (/). Đường dẫn tương đối không được hỗ trợ.
Có thể là nhiều nguồn gốc; nhưng trong trường hợp đó, thông tin xác thực sẽ không được gửi cùng với báo cáo.

Ví dụ

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Sau đó, bạn có thể sử dụng từng điểm cuối được đặt tên trong chính sách thích hợp hoặc sử dụng một điểm cuối duy nhất trên tất cả chính sách.

Đặt tiêu đề ở đâu?

Trong API Báo cáo mới (API được đề cập trong bài đăng này) báo cáo thuộc phạm vi của tài liệu. Tức là đối với một nguồn gốc nhất định, các tài liệu khác nhau (chẳng hạn như site.example/page1 và site.example/page2) có thể gửi báo cáo đến nhiều điểm cuối.

Để nhận báo cáo về các lỗi vi phạm hoặc nội dung không dùng nữa xảy ra trên bất kỳ trang nào của trang web, hãy đặt tiêu đề làm phần mềm trung gian trên tất cả các phản hồi.

Dưới đây là một ví dụ trong Express:

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app.use(function (request, response, next) {
  // Set up the Reporting API
  response.set(
    'Reporting-Endpoints',
    `main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
  );
  next();
});

Lưu ý: API báo cáo mới này khác với API báo cáo cũ (tiêu đề Report-To), trong đó bạn có thể đặt điểm cuối "môi trường xung quanh" cho một trang và tự động nhận báo cáo cho bất kỳ trang nào trên cùng một nguồn gốc. Nếu bạn đang di chuyển từ API Báo cáo cũ sang API Báo cáo mới, hãy xem hướng dẫn di chuyển.

Chỉnh sửa chính sách

Giờ đây, tiêu đề Reporting-Endpoints đã được định cấu hình, hãy thêm lệnh report-to vào từng tiêu đề chính sách mà bạn muốn nhận báo cáo vi phạm. Giá trị của report-to phải là một trong các điểm cuối được đặt tên mà bạn đã định cấu hình.

Bạn có thể sử dụng nhiều điểm cuối cho nhiều chính sách hoặc sử dụng nhiều điểm cuối cho nhiều chính sách.

Đối với mỗi chính sách, giá trị của report-to phải là một trong các điểm cuối được đặt tên mà bạn đã định cấu hình.

report-to không cần thiết cho các báo cáo ngừng sử dụng, can thiệp và sự cố. Các báo cáo này không liên quan đến bất kỳ chính sách nào. Các tệp này được tạo miễn là bạn thiết lập điểm cuối default và gửi đến điểm cuối default này.

Ví dụ:

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

Cảnh báo: Việc sử dụng đúng cú pháp report-to có thể khó khăn vì không phải chính sách nào cũng sử dụng cùng một cấu trúc tiêu đề. Tuỳ thuộc vào chính sách, cú pháp phù hợp có thể là report-to=main-endpoint hoặc report-to main-endpoint. Hãy chuyển đến bản minh hoạ để xem các ví dụ về mã.

Mã mẫu

Để xem tất cả những nội dung này trong ngữ cảnh, bên dưới là một máy chủ Node mẫu sử dụng Express và tập hợp tất cả các phần được thảo luận trong bài viết này. Bài viết này cho biết cách định cấu hình báo cáo cho một số loại báo cáo và hiển thị kết quả.

Gỡ lỗi thiết lập báo cáo

Có chủ đích tạo báo cáo

Khi thiết lập API Báo cáo, có thể bạn sẽ cần cố tình vi phạm chính sách của mình để kiểm tra xem báo cáo có được tạo và gửi như dự kiến hay không. Để xem mã ví dụ vi phạm chính sách và thực hiện các hành vi xấu khác sẽ tạo ra báo cáo thuộc mọi loại, hãy xem bản minh hoạ.

Tiết kiệm thời gian

Báo cáo có thể bị trễ khi gửi – khoảng một phút, đây là khoảng thời gian dài khi gỡ lỗi. ➜ Thật may là khi gỡ lỗi trong Chrome, bạn có thể sử dụng cờ --short-reporting-delay để nhận báo cáo ngay khi báo cáo được tạo.

Chạy lệnh sau trong dòng lệnh để bật cờ này:

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

Sử dụng Công cụ cho nhà phát triển

Trong Chrome, hãy sử dụng DevTools để xem các báo cáo đã gửi hoặc sẽ gửi.

Tính đến tháng 10 năm 2021, tính năng này vẫn đang trong giai đoạn thử nghiệm. Để sử dụng tính năng này, hãy làm theo các bước sau:

Sử dụng Chrome phiên bản 96 trở lên (kiểm tra bằng cách nhập chrome://version vào trình duyệt)
Nhập hoặc dán chrome://flags/#enable-experimental-web-platform-features vào thanh URL của Chrome.
Nhấp vào Đã bật.
Khởi động lại trình duyệt.
Mở Công cụ của Chrome cho nhà phát triển.
Trong Công cụ của Chrome cho nhà phát triển, hãy mở phần Cài đặt. Trong phần Thử nghiệm, hãy nhấp vào Bật bảng điều khiển API Báo cáo trong bảng điều khiển Ứng dụng.
Tải lại Công cụ cho nhà phát triển.
Tải lại trang. Các báo cáo do trang Công cụ cho nhà phát triển tạo ra đang mở sẽ được liệt kê trong bảng điều khiển Ứng dụng của Công cụ cho nhà phát triển của Chrome, trong phần API báo cáo.

Ảnh chụp màn hình DevTools liệt kê các báo cáo — Công cụ của Chrome cho nhà phát triển sẽ hiển thị các báo cáo được tạo trên trang của bạn và trạng thái của các báo cáo đó.

Trạng thái báo cáo

Cột Trạng thái cho bạn biết liệu báo cáo đã được gửi thành công hay chưa.

Trạng thái	Mô tả
`Success`	Trình duyệt đã gửi báo cáo và điểm cuối đã trả lời bằng mã thành công (`200` hoặc một mã phản hồi thành công khác `2xx`).
`Pending`	Trình duyệt hiện đang cố gắng gửi báo cáo.
`Queued`	Báo cáo đã được tạo và trình duyệt hiện không cố gắng gửi báo cáo đó. Báo cáo sẽ xuất hiện dưới dạng `Queued` trong một trong hai trường hợp sau: Báo cáo này là mới và trình duyệt đang chờ xem có thêm báo cáo nào đến hay không trước khi cố gắng gửi báo cáo. Đây không phải là báo cáo mới; trình duyệt đã cố gắng gửi báo cáo này nhưng không thành công và đang chờ trước khi thử lại.
`MarkedForRemoval`	Sau khi thử lại một lúc (`Queued`), trình duyệt đã ngừng gửi báo cáo và sẽ sớm xoá báo cáo đó khỏi danh sách báo cáo cần gửi.

Các báo cáo sẽ bị xoá sau một thời gian, cho dù báo cáo có được gửi thành công hay không.

Lưu ý quan trọng: Trạng thái Queued không phải lúc nào cũng mang lại thông tin vì trạng thái này không thể hiện chính xác việc gửi không thành công hay chưa được thử. Việc sử dụng độ trễ báo cáo ngắn sẽ giúp ích cho: một báo cáo vẫn còn Queued trong trường hợp đó có thể cho thấy việc gửi không thành công.

Khắc phục sự cố

Báo cáo không được tạo hoặc không được gửi đến điểm cuối của bạn như mong đợi? Dưới đây là một vài mẹo để khắc phục sự cố này.

Báo cáo không được tạo

Các báo cáo xuất hiện trong DevTools đã được tạo chính xác. Nếu báo cáo mà bạn muốn xem không xuất hiện trong danh sách này:

Hãy kiểm tra report-to trong các chính sách của bạn. Nếu bạn định cấu hình không đúng, báo cáo sẽ không được tạo. Hãy chuyển đến phần Chỉnh sửa chính sách để khắc phục vấn đề này. Một cách khác để khắc phục sự cố này là kiểm tra bảng điều khiển DevTools trong Chrome: nếu lỗi xuất hiện trong bảng điều khiển cho lỗi vi phạm mà bạn dự kiến, thì điều này có nghĩa là chính sách của bạn có thể đã được định cấu hình đúng cách.
Xin lưu ý rằng chỉ những báo cáo được tạo cho tài liệu mà DevTools đang mở mới xuất hiện trong danh sách này. Ví dụ: nếu trang web site1.example của bạn nhúng một iframe site2.example vi phạm chính sách và do đó tạo ra một báo cáo, thì báo cáo này sẽ chỉ xuất hiện trong DevTools nếu bạn mở iframe trong cửa sổ riêng và mở DevTools cho cửa sổ đó.

Báo cáo được tạo nhưng không được gửi hoặc không được nhận

Nếu bạn có thể xem báo cáo trong Công cụ cho nhà phát triển nhưng điểm cuối của bạn không nhận được báo cáo thì sao?

Lưu ý quan trọng: Vì báo cáo do chính trình duyệt gửi ngoài băng thông chứ không phải một trang web cụ thể, nên các yêu cầu POST chứa báo cáo sẽ không xuất hiện trong bảng điều khiển Mạng của Công cụ dành cho nhà phát triển.

Hãy nhớ sử dụng độ trễ ngắn. Có thể lý do bạn không thấy báo cáo là vì báo cáo đó chưa được gửi!
Kiểm tra cấu hình tiêu đề Reporting-Endpoints. Nếu có vấn đề, báo cáo đã được tạo đúng cách sẽ không được gửi. Trong Công cụ cho nhà phát triển, trạng thái của báo cáo sẽ vẫn là Queued (có thể chuyển tới Pending, sau đó nhanh chóng quay lại Queued khi cố gắng phân phối) trong trường hợp này. Một số lỗi thường gặp có thể gây ra vấn đề này:
Điểm cuối được sử dụng nhưng chưa được định cấu hình. Ví dụ:

Mã có lỗi

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

Báo cáo vi phạm Chính sách tài liệu sẽ được gửi đến endpoint-1, nhưng tên điểm cuối này không được định cấu hình trong Reporting-Endpoints.

Thiếu điểm cuối default. Một số loại báo cáo, chẳng hạn như báo cáo về việc ngừng sử dụng và báo cáo can thiệp, sẽ chỉ được gửi đến điểm cuối có tên là default. Hãy đọc thêm trong phần Định cấu hình tiêu đề Reporting-Endpoints.
Tìm các vấn đề trong cú pháp tiêu đề chính sách, chẳng hạn như thiếu dấu ngoặc kép. Xem chi tiết.
Kiểm tra để đảm bảo điểm cuối của bạn có thể xử lý các yêu cầu đến.
- Đảm bảo rằng điểm cuối của bạn hỗ trợ các yêu cầu trước khi bay của CORS. Nếu không, tài khoản đó sẽ không nhận được báo cáo.
- Kiểm thử hành vi của điểm cuối. Để thực hiện việc này, thay vì tạo báo cáo theo cách thủ công, bạn có thể mô phỏng trình duyệt bằng cách gửi đến các yêu cầu điểm cuối có dạng nội dung mà trình duyệt sẽ gửi. Chạy lệnh sau:
```
curl --header "Content-Type: application/reports+json" \
  --request POST \
  --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
  YOUR_ENDPOINT
```
Điểm cuối của bạn sẽ phản hồi bằng một mã thành công (200 hoặc một mã phản hồi thành công khác 2xx). Nếu không, cấu hình của điểm cuối đó có vấn đề.

Các cơ chế báo cáo có liên quan

Chỉ báo cáo

Các tiêu đề chính sách -Report-Only và Reporting-Endpoints hoạt động cùng nhau.

Các điểm cuối được định cấu hình trong Reporting-Endpoints và được chỉ định trong trường report-to của Content-Security-Policy, Cross-Origin-Embedder-Policy và Cross-Origin-Opener-Policy sẽ nhận được báo cáo khi các chính sách này bị vi phạm.

Bạn cũng có thể chỉ định điểm cuối được định cấu hình trong Reporting-Endpoints trong trường report-to của Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only và Cross-Origin-Opener-Policy-Report-Only. Họ cũng sẽ nhận được báo cáo khi có hành vi vi phạm các chính sách này.

Mặc dù báo cáo được gửi trong cả hai trường hợp, nhưng tiêu đề -Report-Only không thực thi các chính sách: không có nội dung nào bị lỗi hoặc bị chặn, nhưng bạn sẽ nhận được báo cáo về nội dung sẽ bị lỗi hoặc bị chặn.

Lưu ý: Nếu bạn đang sử dụng tiêu đề -Report-Only và đã định cấu hình điểm cuối báo cáo thông qua tiêu đề cũ Report-To, hãy di chuyển sang Reporting-Endpoints nếu có thể. Tìm hiểu thêm trong hướng dẫn di chuyển.

`ReportingObserver`

API JavaScript ReportingObserver có thể giúp bạn quan sát các cảnh báo phía máy khách.

ReportingObserver và tiêu đề Reporting-Endpoints tạo ra các báo cáo có giao diện giống nhau, nhưng hỗ trợ các trường hợp sử dụng hơi khác nhau.

Sử dụng ReportingObserver nếu:

Bạn chỉ muốn theo dõi các nội dung ngừng hoạt động và/hoặc các biện pháp can thiệp của trình duyệt. ReportingObserver cho thấy các cảnh báo phía máy khách, chẳng hạn như ngừng sử dụng và can thiệp của trình duyệt, nhưng không giống như Reporting-Endpoints, tính năng này không ghi lại bất kỳ loại báo cáo nào khác, chẳng hạn như lỗi vi phạm CSP hoặc COOP/COEP.
Bạn cần phải phản ứng với những lỗi vi phạm này theo thời gian thực. ReportingObserver cho phép đính kèm lệnh gọi lại vào một sự kiện vi phạm.
Bạn muốn đính kèm thông tin bổ sung vào một báo cáo để hỗ trợ gỡ lỗi thông qua lệnh gọi lại tuỳ chỉnh.

Một điểm khác biệt nữa là ReportingObserver chỉ được định cấu hình ở phía máy khách: bạn có thể sử dụng thuộc tính này ngay cả khi không có quyền kiểm soát đối với tiêu đề phía máy chủ và không thể đặt Reporting-Endpoints.

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

Hình ảnh chính của Nine Koepfer / @enka80 trên Unsplash, đã chỉnh sửa. Cảm ơn Ian Clelland, Eiji Kitamura và Milica Mihajlija đã xem xét và đưa ra đề xuất về bài viết này.