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

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

Maud Nalpas

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

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

สรุป

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

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

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

⚠️ ในทั้ง 2 กรณี ให้ตรวจสอบว่าได้ตั้งค่าส่วนหัว 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 รองรับรายงานประเภทเดียวกัน ยกเว้น v1 ที่ไม่รองรับรายงานข้อผิดพลาดของเครือข่าย ดูข้อมูลเพิ่มเติมได้ในขั้นตอนการย้ายข้อมูล
• v0 ไม่รองรับและจะไม่รองรับในเบราว์เซอร์ต่างๆ ส่วน v1 มีแนวโน้มที่จะรองรับใน เบราว์เซอร์หลายๆ ตัวในอนาคต

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

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

• Reporting API v1 จะไม่มีผลต่อ 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) มีข้อยกเว้นหนึ่งข้อสำหรับReport-To (v0): หากคุณต้องการใช้การบันทึกข้อผิดพลาดของเครือข่าย ให้ใช้ 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 (v1) ที่ใหม่กว่า โดยรองรับเฉพาะใน Chrome และ Edge คำขอรายงานมีรูปแบบเดียวกับคำขอ Reporting API อื่นๆ และมี Content-Type เดียวกันapplication/reports+json

ไม่แนะนำให้ใช้วิธีแรก (เฉพาะ report-uri) อีกต่อไป และการใช้วิธีที่ 2 มีข้อดีบางประการ โดยเฉพาะอย่างยิ่ง API นี้ช่วยให้คุณใช้วิธีเดียวในการตั้งค่าการรายงานสำหรับรายงานทุกประเภท รวมถึงตั้งค่าปลายทางทั่วไปได้ (เนื่องจากคำขอรายงานทั้งหมดที่สร้างผ่าน 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 header) คุณอาจต้องปรับ 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 ได้เพียงรายการเดียวต่อปลายทาง

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

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 ที่ได้ตรวจสอบและให้คำแนะนำเกี่ยวกับบทความนี้