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

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

Maud Nalpas

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

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

สรุป

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

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

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

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

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

หากคุณดูแลรักษาบริการปลายทางหรือดำเนินการด้วยตนเอง อาจมีการรับส่งข้อมูลมากขึ้นในขณะที่ หรือนักพัฒนาซอฟต์แวร์ภายนอกย้ายข้อมูลไปยัง Reporting API v1 (ส่วนหัว Reporting-Endpoints)

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

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

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

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

• เว็บไซต์สาธิต: 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

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

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

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

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

1. ขั้นตอนที่ 1 (ลงมือเลย): ใช้ส่วนหัวทั้ง 2 แบบ: 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 คุณจะเลือกตั้งค่าปลายทางการรายงานสำหรับการตอบกลับบางรายการเท่านั้นได้ และเลือกเอกสารอื่นๆ ได้ (หน้า) ในต้นทางนั้นจะใช้ "ambient" นี้ ปลายทาง เมื่อใช้ 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 อื่นๆ และ 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)

รูปภาพหลักโดย Nine Koepfer / @enka80 ใน Unแยกต่างหาก, แก้ไขแล้ว ด้วยความขอบคุณจาก Ian Clelland, Eiji Kitamura และ Milica Mihajlija ของ Google