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

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

Maud Nalpas

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

Reporting 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 เวอร์ชัน 1 ไม่ได้ส่งรายงานเป็นกลุ่มเหมือน Reporting API เวอร์ชัน 0 ดังนั้น เมื่อนักพัฒนาแอปพลิเคชันเริ่มย้ายข้อมูลไปยัง 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) ทั้ง 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 ไว้

   ข้อยกเว้น 1 ข้อ: หากต้องการรายงานการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย ให้ใช้ 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 มีข้อดีอยู่ 2-3 ข้อ โดยเฉพาะอย่างยิ่ง จะช่วยให้คุณใช้วิธีเดียวในการตั้งค่าการรายงานสําหรับรายงานทุกประเภท รวมถึงตั้งค่าปลายทางทั่วไปได้ (เนื่องจากคําขอรายงานทั้งหมดที่สร้างผ่าน 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"

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

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

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)

ขอขอบคุณ Ian Clelland, Eiji Kitamura และ Milica Mihajlija ที่ให้การตรวจสอบและคำแนะนำเกี่ยวกับบทความนี้