Reporting API เวอร์ชันใหม่พร้อมใช้งานแล้ว เป็นส่วนตัวและมีแนวโน้มที่จะได้รับการสนับสนุนในเบราว์เซอร์ต่างๆ มากกว่า
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 เป็นกลไกใหม่ดังกล่าว
การสาธิตและโค้ด
- เว็บไซต์สาธิต: 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
- ขอบเขตของรายงานจะแตกต่างกัน
เมื่อใช้ v0 คุณจะตั้งค่าปลายทางการรายงานสําหรับการตอบกลับบางรายการเท่านั้นได้ เอกสารอื่นๆ (หน้า) ในต้นทางนั้นจะใช้ปลายทางแอมเบียนท์เหล่านี้โดยอัตโนมัติ
เมื่อใช้ v1 คุณต้องตั้งค่าส่วนหัว Reporting-Endpoints
สำหรับคำตอบทั้งหมดที่อาจสร้างรายงาน
- API ทั้งสองรองรับรายงานประเภทเดียวกัน โดยมีข้อยกเว้น 1 ข้อคือ v1 ไม่รองรับรายงานข้อผิดพลาดเกี่ยวกับเครือข่าย อ่านเพิ่มเติมในขั้นตอนการย้ายข้อมูล
- v0 ไม่สามารถทำได้และจะไม่ได้รับการสนับสนุนในเบราว์เซอร์ต่างๆ v1 มีการสนับสนุนมากขึ้นในเบราว์เซอร์ต่างๆ ในอนาคต
สิ่งที่ยังคงไม่เปลี่ยนแปลง
- รูปแบบและโครงสร้างของรายงานไม่มีการเปลี่ยนแปลง
- คำขอที่เบราว์เซอร์ส่งไปยังปลายทางจะยังคงเป็นคำขอ
POST
ของContent-type
application/reports+json
- ระบบรองรับการจับคู่ปลายทางบางรายการกับรายงานบางประเภททั้ง v0 และ v1
- บทบาทของปลายทาง
default
จะไม่เปลี่ยนแปลง Reporting API v1 ไม่มีผลต่อ
ReportingObserver
ReportingObserver
ยังคงมีสิทธิ์เข้าถึงรายงานที่สังเกตได้ทั้งหมดต่อไปและรูปแบบก็เหมือนกัน
ความแตกต่างทั้งหมดระหว่าง v0 และ v1
Legacy Reporting API (v0) ส่วนหัว Report-To |
ส่วนหัว Reporting API ใหม่ (v1)Reporting-Endpoints |
|
---|---|---|
การสนับสนุนเบราว์เซอร์ | Chrome 69+ และ Edge 69+ | Chrome 96+ และ Edge 96+ รองรับ Firefox Safari ไม่ปฏิเสธ ดูสัญญาณของเบราว์เซอร์ |
ปลายทาง | ส่งรายงานไปยังผู้รวบรวมรายงานหลายรายการใดก็ได้ (มีการระบุ URL หลายรายการต่อกลุ่มปลายทาง) | ส่งรายงานไปยังเครื่องมือรวบรวมรายงานที่ต้องการ (กำหนด URL เพียง 1 รายการต่อปลายทางเท่านั้น) |
แพลตฟอร์ม API | ใช้ส่วนหัว `Report-To` เพื่อกำหนดค่ากลุ่มปลายทางที่มีชื่อ |
ใช้ส่วนหัว `Reporting-Endpoints` เพื่อกำหนดค่าปลายทางที่มีชื่อ |
ประเภทของรายงานที่สามารถสร้างผ่าน API นี้ |
|
ไม่เปลี่ยนแปลง ยกเว้นจาก Network Error Logging (NEL): ระบบไม่รองรับฟีเจอร์นี้ใน Reporting API ใหม่ (v1) |
ขอบเขตรายงาน | ต้นทางของคุณเป็นเจ้าของเอกสารนั้น ส่วนหัว Report-To ของเอกสารจะมีผลกับเอกสารอื่นๆ (หน้า) จากต้นทางนั้น
ช่อง url ของรายงานจะยังคงแตกต่างกันไปตามเอกสาร
|
เอกสาร ส่วนหัว Reporting-Endpoints ของเอกสารจะมีผลกับเอกสารนั้นเท่านั้น
ช่อง url ของรายงานจะยังคงแตกต่างกันไปตามเอกสาร
|
การแยกรายงาน (แบบกลุ่ม) | ระบบจะรวมเอกสาร (หน้า) หรือเว็บไซต์/ต้นทางที่ต่างกันซึ่งสร้างรายงานในช่วงเวลาเดียวกันและมีปลายทางการรายงานเดียวกันอยู่รวมกันเป็นกลุ่ม โดยจะส่งไปที่ปลายทางการรายงานในข้อความเดียวกัน |
|
การรองรับการจัดสรรภาระงาน / ลำดับความสำคัญ | ใช่ | ไม่ได้ |
นักพัฒนาปลายทาง: คาดว่าจะมีการเข้าชมมากขึ้น
หากคุณตั้งค่าเซิร์ฟเวอร์ของคุณเองเป็นปลายทางการรายงาน หรือหากกำลังพัฒนาหรือบำรุงรักษาบริการเครื่องมือรวบรวมรายงาน คุณอาจได้รับการเข้าชมปลายทางดังกล่าวมากขึ้น
เนื่องจากรายงานไม่ได้รวมกลุ่มกับ 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 เวอร์ชัน 1 ยังไม่รองรับการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย เราจะพัฒนากลไกใหม่สำหรับการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย ⏤ จนกว่าจะพร้อมใช้งาน ให้ใช้ Reporting API v0 หากต้องการการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่ายควบคู่ไปกับรายงานประเภทอื่นๆ ให้ใช้ทั้งReport-To
(v0) และReporting-Endpoints
(v1) v0 จะให้การบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย และ v1 จะส่งรายงานประเภทอื่นทั้งหมดให้คุณ
ขั้นตอนการย้ายข้อมูล
เป้าหมายของการย้ายข้อมูลนี้คือรายงานที่ไม่สูญหายที่คุณเคยได้รับใน v0
ขั้นตอนที่ 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- รายงานจากไคลเอ็นต์ Chrome และ Edge เวอร์ชันใหม่ด้วย
ขั้นตอนที่ 2 (ทำเลย): ตรวจดูว่าได้ตั้งค่าส่วนหัว
Reporting-Endpoints
ในคำตอบทั้งหมดที่อาจสร้างรายงานแล้วเมื่อใช้ v0 คุณจะเลือกที่จะตั้งค่าปลายทางการรายงานสำหรับการตอบกลับบางรายการเท่านั้นได้ และเอกสารอื่นๆ (หน้า) ในต้นทางนั้นจะใช้ปลายทาง "ambient" นี้ เมื่อใช้ v1 เนื่องจากการกำหนดขอบเขตมีความแตกต่าง คุณจึงต้องตั้งค่าส่วนหัว
Reporting-Endpoints
ในคำตอบทั้งหมดที่อาจสร้างรายงานขั้นตอนที่ 3 (เริ่มภายหลัง): เมื่อผู้ใช้ทั้งหมดหรือส่วนใหญ่อัปเดตเป็นการติดตั้ง Chrome หรือ Edge ภายหลัง (96 ขึ้นไป) ให้นำ
Report-To
(v0) ออกและเก็บไว้เพียงReporting-Endpoints
เท่านั้นข้อยกเว้นเพียงอย่างเดียวคือหากคุณต้องการรายงานการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย ให้เก็บ
Report-To
ไว้จนกว่าจะใช้กลไกใหม่สำหรับการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย
ดูตัวอย่างโค้ดในตำราการย้ายข้อมูล
ขั้นตอนการย้ายข้อมูลสำหรับการรายงาน CSP
คุณกำหนดค่ารายงานการละเมิดนโยบายรักษาความปลอดภัยเนื้อหาได้ 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 (ทำเลย): หากยังไม่ได้เพิ่ม ให้เพิ่ม
report-to
ไว้ข้างreport-uri
เบราว์เซอร์ที่รองรับเฉพาะreport-uri
(Firefox) จะใช้report-uri
ส่วนเบราว์เซอร์ที่รองรับreport-to
(Chrome, Edge) จะใช้report-to
ด้วย หากต้องการระบุปลายทางที่มีชื่อที่คุณจะใช้ในreport-to
ให้ใช้ทั้งส่วนหัวReport-To
และReporting-Endpoints
วิธีนี้ช่วยให้มั่นใจว่าคุณจะได้รับรายงานจากไคลเอ็นต์ Chrome และ Edge เวอร์ชันเก่าและใหม่ขั้นตอนที่ 3 (เริ่มภายหลัง): เมื่อผู้ใช้ทั้งหมดหรือส่วนใหญ่อัปเดตเป็นการติดตั้ง Chrome หรือ Edge ภายหลัง (96 ขึ้นไป) ให้นำ
Report-To
(v0) ออกและเก็บไว้เพียงReporting-Endpoints
เท่านั้น เก็บreport-uri
ไว้เพื่อให้ยังคงได้รับรายงานสำหรับเบราว์เซอร์ที่รองรับเท่านั้น
ดูตัวอย่างโค้ดสำหรับขั้นตอนเหล่านี้ในการย้ายข้อมูลการรายงาน CSE
การย้ายข้อมูล: โค้ดตัวอย่าง
ภาพรวม
หากใช้ Reporting API เดิม (v0) เพื่อรับรายงานการละเมิดสำหรับ COOP
(ส่วนหัว Cross-Origin-Opener-Policy
), COEP (Cross-Origin-Embedder-Policy
) หรือนโยบายเอกสาร
(ส่วนหัว Document-Policy
): คุณไม่จำเป็นต้องเปลี่ยนส่วนหัวของนโยบายด้วยตนเองเมื่อย้ายข้อมูลไปยัง Reporting API เวอร์ชัน 1 คุณจำเป็นจะต้องย้ายข้อมูลจากส่วนหัว 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 ใน Unlash, แก้ไข ขอขอบคุณ Ian Clelland, Eiji Kitamura และ Milica Mihajlija สำหรับรีวิวและคำแนะนำในบทความนี้