יש גרסה חדשה של Reporting API. הוא פרטי יותר ויש יותר סיכוי שהוא ייתמך בכל הדפדפנים.
Reporting API מודיע לכם על שגיאות שמתרחשות באתר כשמבקרים משתמשים בו. הוא מספק מידע על התערבות בדפדפן, קריסות של הדפדפן, הפרות של מדיניות האבטחה בתוכן, הפרות של COOP/COEP, אזהרות על הוצאה משימוש ועוד.
יש גרסה חדשה של Reporting API. ה-API החדש קטן יותר וסביר יותר שהוא יתמוך בדפדפנים שונים.
סיכום
מפתחי אתרים
אם כבר יש לכם פונקציונליות דיווח באתר: עוברים ל-V1 באמצעות הכותרת החדשה (Reporting-Endpoints
), אבל משאירים את הכותרת מהדור הקודם לזמן מה (Report-To
).
מידע נוסף זמין במאמר העברה: קוד לדוגמה.
אם אתם מוסיפים לאתר פונקציונליות של דיווח ממש עכשיו: השתמשו רק בכותרת החדשה (Reporting-Endpoints
).
⚠️ בשני המקרים, הקפידו להגדיר את הכותרת Reporting-Endpoints
בכל התגובות שעשויות ליצור דוחות.
מפתחים של שירותי דיווח
אם אתם מתחזקים שירות של נקודת קצה או מפעילים שירות משלכם, צפוי ליותר תנועה בזמן המעבר שלכם או של מפתחים חיצוניים ל-Reporting API v1 (הכותרת Reporting-Endpoints
).
בהמשך תוכלו למצוא פרטים וקוד לדוגמה.
רישום של שגיאת רשת
אנחנו נוסיף מנגנון חדש לרישום שגיאות רשת. ברגע שהאפשרות הזו תהיה זמינה, עוברים מ-Reporting API v0 למנגנון החדש הזה.
הדגמה (דמו) וקוד
- אתר הדגמה: API חדש לדיווח (גרסה 1)
- קוד לאתר ההדגמה
ההבדלים בין 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 לא תומכת בדוחות של שגיאות רשת. מידע נוסף זמין במאמר שלבי ההעברה.
- v0 לא נתמכת ולא נתמכת בכל הדפדפנים. סביר יותר להניח שיתמכו ב-v1 בכמה דפדפנים בעתיד.
מה שנשאר ללא שינוי
- הפורמט והמבנה של הדוחות לא השתנו.
- הבקשה שהדפדפן שלח לנקודת הקצה נשארת כבקשת
POST
שלContent-type
application/reports+json
. - מיפוי נקודות קצה מסוימות לסוגי דוחות מסוימים נתמך גם ב-v0 וגם ב-v1.
- התפקיד של נקודת הקצה
default
לא השתנה. לגרסה 1 של Reporting API אין השפעה על
ReportingObserver
.ReportingObserver
ממשיך לקבל גישה לכל הדוחות הגלויים, והפורמט שלהם זהה.
כל ההבדלים בין v0 לבין v1
Legacy Reporting API (v0) הכותרת Report-To |
כותרת Reporting-Endpoints חדשהשל Reporting API |
|
---|---|---|
תמיכת דפדפן | Chrome מגרסה 69 ואילך ו-Edge 69 ואילך. | Chrome מגרסה 96 ואילך ו-Edge 96 ואילך. Firefox תומך. Safari לא מתנגד. להצגת אותות של הדפדפן. |
נקודות קצה (endpoints) | שליחת דוחות לכל אוספי דוחות מספר (מספר כתובות URL שהוגדרו לכל קבוצה של נקודות קצה). | נשלחים דוחות לאוספי דוחות ספציפיים (מוגדרת רק כתובת URL אחת לכל נקודת קצה). |
פלטפורמת API | משתמשת בכותרת `Report-To` כדי להגדיר קבוצות של נקודות קצה בעלות שם. |
משתמשת בכותרת `Reporting-Endpoints` כדי להגדיר נקודות קצה בעלות שם. |
סוגי הדוחות שאפשר ליצור באמצעות ה-API הזה |
|
ללא שינוי, מלבד Network Error Logging (NEL): התכונה הזו לא נתמכת ב-Reporting API החדש (v1). |
היקף הדוח | מקור. הכותרת Report-To של מסמך משפיעה על מסמכים אחרים (דפים) מאותו מקור.
השדה url בדוח עדיין משתנה בהתאם למסמך.
|
מסמך. הכותרת Reporting-Endpoints של מסמך משפיעה רק על המסמך הזה.
השדה url בדוח עדיין משתנה בהתאם למסמך.
|
דיווח על בידוד (באצווה) | מסמכים (דפים) או אתרים/מקורות שונים שיוצרים דוח בערך באותו זמן ושיש להם אותה נקודת קצה לדיווח יקובצו יחד: הם יישלחו באותה הודעה לנקודת הקצה של הדיווח. |
|
תמיכה באיזון עומסים / סדרי עדיפויות | כן | לא |
מפתחים של נקודות קצה (endpoint): צפוי נפח תנועה גדול יותר
אם הגדרתם שרת משלכם כנקודת קצה לדיווח, או אם אתם מפתחים או מתחזקים אוסף דוחות כשירות, תוכלו לצפות ליותר תנועה לנקודת הקצה הזו.
הסיבה לכך היא שהדוחות לא מקובצים יחד עם Reporting API v1 כמו גם עם Reporting API v0. לכן, כשמפתחי אפליקציות יתחילו לעבור ל-Reporting API v1, מספר הדוחות ימשיך להיות דומה, אבל נפח הבקשות לשרת נקודות הקצה יגדל.
מפתחי אפליקציות: העברה אל Reporting-Endpoints
(גרסה 1)
מה עליך לעשות?
לשימוש בגרסה החדשה של Reporting API (גרסה 1) יש כמה יתרונות ✅:
- האותות בדפדפן הם חיוביים, כלומר אפשר לצפות לתמיכה בדפדפנים שונים בגרסה 1 (בשונה מ-v0 שנתמכת רק ב-Chrome וב-Edge).
- ה-API פחות רציף.
- אנחנו מפתחים את הכלים סביב גרסה 1 של Reporting API.
לכן, אנחנו מביאים בחשבון את הנקודות הבאות:
- אם באתר שלכם כבר נעשה שימוש ב-Reporting API v0 עם הכותרת
Report-To
, עליכם לעבור ל-Reporting API v1 (למידע נוסף, קראו את שלבי ההעברה). אם באתר שלכם כבר נעשה שימוש בפונקציונליות דיווח על הפרות של מדיניות האבטחה התוכן, עיינו בשלבי ההעברה הספציפיים לדיווח על CSP. - אם לא השתמשתם עדיין ב-Reporting API באתר ואתם מוסיפים עכשיו פונקציונליות דיווח: השתמשו ב-Reporting API החדש (v1) (הכותרת
Reporting-Endpoints
). יש יוצא מן הכלל אחד: אם אתם צריכים להשתמש ב-Network Error Logging, השתמשו ב-Report-To
(v0). בשלב 1, אין תמיכה ברישום שגיאות רשת ב-Reporting API v1. אנחנו נוסיף מנגנון חדש ל'רישום שגיאות רשת' עד שיהיה זמין, צריך להשתמש ב-Reporting API v0. אם אתם צריכים רישום ביומן של שגיאות רשת לצד סוגי דוחות אחרים, השתמשו גם ב-Report-To
(v0) וגם ב-Reporting-Endpoints
(v1). בגרסה v0 תוכלו להירשם ל-Network Error Logging ו-v1 נותנת לכם דוחות על כל הסוגים האחרים.
שלבי ההעברה
המטרה שלכם בהעברה הזו היא לא לאבד את הדוחות שהשתמשתם בהם כדי לקבל את הגרסה v0.
שלב 1 (עשה עכשיו): שימוש בשתי הכותרות:
Report-To
(v0) ו-Reporting-Endpoints
(v1).בדרך הזו, אתם מקבלים:
- דוחות מלקוחות Chrome ו-Edge חדשים יותר, הודות ל-
Reporting-Endpoints
(גרסה 1). - דוחות מלקוחות ישנים של Chrome ו-Edge, הודות ל-
Report-To
(גרסה 0).
מכונות דפדפן שתומכות ב-
Reporting-Endpoints
ישתמשו ב-Reporting-Endpoints
, ובמכונות שלא תומכות ב-Report-To
. פורמט הבקשה והדוח זהים ב-v0 וב-v1.- דוחות מלקוחות Chrome ו-Edge חדשים יותר, הודות ל-
שלב 2 (עשה עכשיו): מוודאים שהכותרת
Reporting-Endpoints
מוגדרת בכל התגובות שעשויות ליצור דוחות.ב-v0 תוכלו להגדיר נקודות קצה לדיווח רק בחלק מהתגובות, ומסמכים אחרים (דפים) במקור הזה ישתמשו בנקודת הקצה 'סביבתית'. ב-v1, בגלל ההבדל בהיקף, אתם צריכים להגדיר את הכותרת
Reporting-Endpoints
בכל התגובות שעשויות להפיק דוחות.שלב 3 (התחלה מאוחר יותר): לאחר שכל המשתמשים או רוב המשתמשים יעדכנו את Chrome או את Edge למועד מאוחר יותר (96 ואילך), יש להסיר את
Report-To
(v0) ולהשאיר רק אתReporting-Endpoints
.יוצא מן הכלל: אם אתם בכל זאת צריכים דוחות של רישום שגיאות רשת, צריך להשאיר את השדה
Report-To
עד שתתקבל מנגנון חדש ל'רישום שגיאות רשת'.
אפשר לראות דוגמאות לקוד בספר המתכונים של העברה.
שלבי ההעברה לדיווח של CSP
יש שתי דרכים להגדיר דוחות על הפרות של מדיניות Content-Security-Policy:
- כאשר הכותרת 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
) לא מומלץ יותר ולשימוש בגישה השנייה יש כמה יתרונות. באופן ספציפי, הדוח מאפשר להשתמש בדרך אחת להגדרת דיווח לכל סוגי הדוחות וגם להגדיר נקודת קצה כללית (endpoint) (כי כל הבקשות לדיווח שנוצרו דרך 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 חדשים יותר וגם מלקוחות Chrome ו-Edge חדשים יותר.שלב 3 (התחלה מאוחר יותר): לאחר שכל המשתמשים או רוב המשתמשים יעדכנו את Chrome או את Edge למועד מאוחר יותר (96 ואילך), יש להסיר את
Report-To
(v0) ולהשאיר רק אתReporting-Endpoints
. משאירים אתreport-uri
כדי להמשיך לקבל דוחות רק לדפדפנים שתומכים בו.
במאמר העברה של דוחות CSP אפשר לעיין בדוגמאות לקוד של השלבים האלה.
מיגרציה: קוד לדוגמה
סקירה כללית
אם אתם משתמשים בגרסה הקודמת של Reporting API (גרסה 0) כדי לקבל דוחות על הפרות של COOP (כותרת Cross-Origin-Opener-Policy
), COEP (Cross-Origin-Embedder-Policy
) או מדיניות מסמך (הכותרת Document-Policy
): אין צורך לשנות את כותרות המדיניות האלה עצמן כשעוברים לגרסה 1 של Reporting API. מה שצריך לעשות הוא לעבור מהכותרת הקודמת 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 (גרסה 0)
- מפרט: גרסה חדשה של Reporting API (גרסה 1)
תמונה ראשית (Hero) מאת Nine Koepfer / @enka80 ב-UnFlood, נערכה. תודה רבה לאיאן קלילנד, אייג'י קיטמורה ומיליקה מיהג'ליג'ה על הביקורות וההצעות שלהם במאמר הזה.