ย้ายข้อมูลไปยัง Reporting API v1

API การรายงานเวอร์ชันใหม่พร้อมใช้งานแล้ว เนื่องจากมีความเป็นส่วนตัวมากกว่าและมีโอกาสที่เบราว์เซอร์ต่างๆ จะรองรับ

Maud Nalpas

Reporting API จะแจ้งให้คุณทราบเกี่ยวกับข้อผิดพลาดที่เกิดขึ้นในเว็บไซต์เมื่อผู้เข้าชมใช้งาน ซึ่งจะช่วยให้คุณเห็นการแทรกแซงเบราว์เซอร์ การขัดข้องของเบราว์เซอร์ การละเมิดนโยบายรักษาความปลอดภัยเนื้อหา การละเมิด COOP/COEP คำเตือนการเลิกใช้งาน และอื่นๆ

API การรายงานเวอร์ชันใหม่พร้อมใช้งานแล้ว API ใหม่นี้ใช้ทรัพยากรน้อยลงและมีแนวโน้มที่จะรองรับการใช้งานในเบราว์เซอร์ต่างๆ มากขึ้น

สรุป

นักพัฒนาเว็บไซต์

หากมีฟังก์ชันการรายงานสําหรับเว็บไซต์อยู่แล้ว ให้ย้ายข้อมูลไปยัง v1 โดยใช้ส่วนหัวใหม่ (Reporting-Endpoints) แต่เก็บส่วนหัวเดิมไว้ใช้อีกสักระยะ (Report-To) ดูการย้ายข้อมูล: ตัวอย่างโค้ด

หากเพิ่งเพิ่มฟังก์ชันการรายงานลงในเว็บไซต์ ให้ใช้เฉพาะส่วนหัวใหม่ (Reporting-Endpoints)

⚠️ ไม่ว่าจะในกรณีใด โปรดตั้งค่าส่วนหัว Reporting-Endpoints ในการตอบกลับทั้งหมดที่อาจสร้างรายงาน

นักพัฒนาบริการรายงาน

หากคุณดูแลรักษาบริการปลายทางหรือดําเนินการบริการของคุณเอง โปรดทราบว่าคุณหรือนักพัฒนาแอปภายนอกอาจได้รับปริมาณการเข้าถึงมากขึ้นเมื่อย้ายข้อมูลไปยัง Reporting API v1 (ส่วนหัว Reporting-Endpoints)

โปรดอ่านต่อเพื่อดูรายละเอียดและโค้ดตัวอย่าง

การบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย

เราจะพัฒนากลไกใหม่สำหรับการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย เมื่อพร้อมใช้งาน ให้เปลี่ยนจาก Reporting API v0 ไปใช้กลไกใหม่ดังกล่าว

การสาธิตและโค้ด

• เว็บไซต์สาธิต: Reporting API ใหม่ (v1)
• โค้ดสำหรับเว็บไซต์สาธิต

ความแตกต่างระหว่าง v0 กับ v1

สิ่งที่จะเปลี่ยนแปลง

• แพลตฟอร์ม API จะแตกต่างออกไป

 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

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

• ขอบเขตของรายงานแตกต่างกัน

• ทั้ง 2 API รองรับรายงานประเภทเดียวกัน โดยมีข้อยกเว้น 1 ข้อคือ v1 ไม่รองรับรายงานข้อผิดพลาดของเครือข่าย อ่านเพิ่มเติมในขั้นตอนการย้ายข้อมูล
• v0 ยังไม่รองรับและจะไม่รองรับในเบราว์เซอร์ต่างๆ ส่วน v1 มีแนวโน้มที่จะรองรับในเบราว์เซอร์หลายรุ่นในอนาคต

สิ่งที่ยังคงเหมือนเดิม

• รูปแบบและโครงสร้างของรายงานไม่มีการเปลี่ยนแปลง
• คำขอที่เบราว์เซอร์ส่งไปยังปลายทางจะยังคงเป็นคำขอ POST ของ Content-type application/reports+json
• การแมปปลายทางบางรายการกับรายงานบางประเภทใช้ได้ทั้งใน v0 และ v1
• บทบาทของปลายทาง default จะไม่มีการเปลี่ยนแปลง

• Reporting API เวอร์ชัน 1 ไม่มีผลต่อ ReportingObserver ReportingObserver จะยังคงมีสิทธิ์เข้าถึงรายงานที่สังเกตได้ทั้งหมดและรูปแบบของรายงานจะเหมือนกัน

ความแตกต่างทั้งหมดระหว่าง v0 กับ v1

นักพัฒนาแอปเกี่ยวกับอุปกรณ์ปลายทาง: คาดว่าจะมีการเข้าชมมากขึ้น

หากคุณตั้งค่าเซิร์ฟเวอร์ของคุณเองเป็นปลายทางการรายงาน หรือหากกำลังพัฒนาหรือบำรุงรักษาเครื่องมือรวบรวมรายงานเป็นบริการ ก็คาดว่าจะมีการเข้าชมปลายทางดังกล่าวเพิ่มขึ้น

เนื่องจากรายงานไม่ได้จัดกลุ่มตาม Reporting API v1 เหมือนกับรายงานที่มี Reporting API v0 ดังนั้น เมื่อนักพัฒนาแอปพลิเคชันเริ่มย้ายข้อมูลไปยัง 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) มีข้อยกเว้น 1 ข้อคือ หากคุณต้องการใช้การบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย ให้ใช้ Report-To (v0) ขณะนี้ Reporting API v1 ยังไม่รองรับการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย เราจะพัฒนากลไกใหม่สำหรับการบันทึกข้อผิดพลาดของเครือข่าย⏤จนกว่ากลไกดังกล่าวจะพร้อมใช้งาน ให้ใช้ Reporting API v0 หากต้องการใช้การบันทึกข้อผิดพลาดของเครือข่ายควบคู่ไปกับรายงานประเภทอื่นๆ ให้ใช้ Report-To (v0) และ Reporting-Endpoints (v1) ทั้ง 2 รายการ โดย v0 จะให้การบันทึกข้อผิดพลาดของเครือข่าย และ v1 จะให้รายงานประเภทอื่นๆ ทั้งหมด

ขั้นตอนการย้ายข้อมูล

เป้าหมายในการย้ายข้อมูลนี้คือไม่สูญเสียรายงานที่คุณเคยได้รับจาก v0

1. ขั้นตอนที่ 1 (ทําเลย): ใช้ทั้งส่วนหัว Report-To (v0) และ Reporting-Endpoints (v1)

   ซึ่งคุณจะได้รับสิทธิประโยชน์ต่อไปนี้

   • รายงานจากไคลเอ็นต์ Chrome และ Edge รุ่นใหม่ด้วย Reporting-Endpoints (v1)
   • รายงานจากไคลเอ็นต์ 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 มี 2 วิธีดังนี้

• มีส่วนหัว CSP เพียงอย่างเดียวผ่านคำสั่ง report-uri ซึ่งรองรับเบราว์เซอร์ได้หลากหลาย เช่น Chrome, Firefox, Safari และ Edge ระบบจะส่งรายงานที่มีประเภทเนื้อหา application/csp-report และมีรูปแบบสำหรับ CSP โดยเฉพาะ รายงานเหล่านี้เรียกว่า "รายงาน CSP ระดับ 2" และไม่อาศัย Reporting API
• เมื่อใช้ Reporting API คุณจะส่งผ่านข้อมูลได้ผ่านส่วนหัว Report-To (เดิม) หรือ Reporting-Endpoints (เวอร์ชัน 1) ที่ใหม่กว่า การดำเนินการนี้มีการสนับสนุนใน Chrome และ Edge เท่านั้น คำขอรายงานมีรูปแบบเดียวกับคำขอ Reporting API อื่นๆ และ application/reports+json ที่มีเนื้อหาประเภทเดียวกัน

ไม่แนะนำให้ใช้วิธีแรก (เพียง report-uri เท่านั้น) และการใช้วิธีที่ 2 ก็มีประโยชน์เล็กน้อย โดยเฉพาะอย่างยิ่ง จะช่วยให้คุณใช้วิธีเดียวในการตั้งค่าการรายงานสําหรับรายงานทุกประเภท รวมถึงตั้งค่าปลายทางทั่วไปได้ (เนื่องจากคําขอรายงานทั้งหมดที่สร้างผ่าน Reporting API⏤CSP และอื่นๆ⏤มีรูปแบบเดียวกัน application/reports+json

อย่างไรก็ตาม มีเพียงไม่กี่เบราว์เซอร์ที่รองรับ report-to ดังนั้น เราขอแนะนำให้ใช้ report-uri ควบคู่ไปกับแนวทาง Reporting API (Report-To หรือ Reporting-Endpoints จะให้ดีกว่า) เพื่อรับรายงานการละเมิด CSP จากเบราว์เซอร์หลายรายการ ในเบราว์เซอร์ที่รู้จัก report-uri และ report-to ระบบจะไม่สนใจ report-uri หากมี report-to ในเบราว์เซอร์ที่รองรับเฉพาะ 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 ต่อไปเพื่อให้ยังคงได้รับรายงานสำหรับเบราว์เซอร์ที่รองรับเฉพาะเบราว์เซอร์นั้น

ดูตัวอย่างโค้ดสำหรับขั้นตอนเหล่านี้ในการย้ายข้อมูลการรายงาน 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) คุณอาจต้องปรับแต่ง Content-Security-Policy ในขั้นตอนการย้ายข้อมูลไปยัง Reporting API ใหม่ (v1)

การย้ายข้อมูลขั้นพื้นฐาน

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

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" }] }

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

โปรดทราบว่าเมื่อใช้ v1 คุณยังคงส่งประเภทรายงานเฉพาะไปยังปลายทางที่เฉพาะเจาะจงได้ แต่สามารถมี URL ได้เพียง 1 รายการต่อปลายทาง

สังเกตการณ์ทุกหน้า

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

// 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(...)
});

การย้ายข้อมูลการรายงาน CSP

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

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

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

อ่านเพิ่มเติม

• ตรวจสอบเว็บแอปพลิเคชันด้วย Reporting API (โพสต์หลักเกี่ยวกับ Reporting API)
• ข้อมูลจำเพาะ: Reporting API เดิม (v0)
• ข้อมูลจำเพาะ: Reporting API ใหม่ (v1)

ขอขอบคุณ IanClelland, Eiji Kitamura และ Milica Mihajlija สำหรับรีวิวและคำแนะนำในบทความนี้