מעבר ל-Reporting API גרסה 1

יש גרסה חדשה של Reporting API. הוא פרטי יותר ויש סיכוי גבוה יותר שתהיה תמיכה בו בדפדפנים שונים.

Maud Nalpas
Maud Nalpas

ה-Reporting API מאפשר לכם לקבל הודעות על שגיאות שמתרחשות באתר בזמן שהמבקרים משתמשים בו. הוא נותן את החשיפה של התערבות בדפדפן, קריסות של דפדפנים, הפרות מדיניות אבטחת תוכן, הפרות של COOP/COEP, אזהרות לגבי הוצאה משימוש ועוד.

יש גרסה חדשה של Reporting API. ה-API החדש דק יותר, ויש סבירות גבוהה יותר שהוא נתמך בכל הדפדפנים.

סיכום

מפתחי אתרים

אם כבר יש לכם פונקציונליות דיווח באתר: עוברים לגרסה 1 באמצעות הכותרת החדשה. (Reporting-Endpoints), אבל להשאיר את הכותרת מהדור הקודם למשך זמן מה (Report-To). מידע נוסף זמין בקטע העברה: קוד לדוגמה.

אם אתם מוסיפים כרגע פונקציונליות דיווח לאתר: השתמשו רק בכותרת החדשה (Reporting-Endpoints).

⚠️ בשני המקרים, חשוב להגדיר את הכותרת Reporting-Endpoints בכל התשובות שעשויות להיות להפיק דוחות.

מפתחים של שירותי דיווח

אם אתם מתחזקים שירות של נקודת קצה או מפעילים שירות משלכם, כדאי לצפות לנפח תנועה גדול יותר במהלך השימוש או מפתחים חיצוניים עוברים ל-Reporting API v1 (הכותרת Reporting-Endpoints).

בהמשך מופיעים פרטים וקוד לדוגמה.

רישום של שגיאות רשת

נפתח מנגנון חדש לרישום שגיאות רשת. ברגע שזה יהיה זמין, צריך לעבור מ-Reporting API גרסה 0 למנגנון החדש.

הדגמה וקוד

ההבדלים בין גרסה v0 לבין גרסה 1

מה עומד להשתנות

  • פלטפורמת ה-API שונה.
v0 (מדור קודם)
 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

{0 משתמש בכותרת Report-To כדי להגדיר קבוצות של נקודות קצה בעלות שם, ובהוראה report-to בכותרות אחרות כדי להפנות לקבוצות של נקודות הקצה האלה.

גרסה 1 (חדש)
 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

v1 משתמשת בכותרת Reporting-Endpoints כדי להגדיר בעלי שם נקודות קצה (endpoints). בדומה לגרסה 0, היא משתמשת בהוראה report-to בכותרות אחרות כדי להפנות לקבוצות של נקודות הקצה האלה.

  • היקף הדוח שונה.
v0 (מדור קודם)

אם משתמשים בגרסה 0, אפשר להגדיר נקודות קצה לדיווח רק על תשובות מסוימות. מסמכים (דפים) אחרים המקור ישתמש אוטומטית בנקודות הקצה ברקע.

גרסה 1 (חדש)

בגרסה 1, צריך להגדיר את הכותרת Reporting-Endpoints בכל התשובות שעשויות ליצור דוחות.

  • שני ממשקי ה-API תומכים באותם סוגי דוחות, למעט חריג אחד: גרסה 1 לא תומכת בדוחות שגיאות רשת. מידע נוסף זמין בשלבי ההעברה.
  • אין תמיכה ב-v0 בכל הדפדפנים, ולא תהיה אפשרות לתמוך בה. יש סבירות גבוהה יותר שתהיה תמיכה בגרסה 1 בדפדפנים מרובים בעתיד.

מה לא משתנה

  • הפורמט והמבנה של הדוחות לא השתנו.
  • הבקשה שנשלחה על ידי הדפדפן לנקודת הקצה נשארת בקשת POST של Content-type application/reports+json.
  • מיפוי של נקודות קצה (endpoints) מסוימות לסוגי דוחות מסוימים נתמך גם בגרסה v0 וגם בגרסה 1.
  • התפקיד של נקודת הקצה default לא משתנה.
  • לגרסה 1 של Reporting API אין השפעה על ReportingObserver. האפליקציה ReportingObserver ממשיכה לקבל גישה לכל הדוחות הגלויים, והפורמט שלהם הוא זהה.

כל ההבדלים בין גרסה v0 לבין גרסה 1

Legacy Reporting API (גרסה 0)
כותרת Report-To
Reporting API החדש (גרסה 1)
כותרת Reporting-Endpoints
תמיכה בדפדפנים Chrome מגרסה 69 ואילך ו-Edge 69 ואילך. Chrome מגרסה 96 ואילך ו-Edge מגרסה 96 ואילך. Firefox תומך. אין ל-Safari התנגדות. מעיינים בקטע אותות מהדפדפן.
נקודות קצה (endpoints) שולחת דוחות לכל מספר אוספים של דוחות (מוגדרות כמה כתובות URL לכל קבוצה של נקודות קצה). שולחת דוחות לאוסף דוחות ספציפיים (רק כתובת URL אחת מוגדרת לכל נקודת קצה).
פלטפורמת API נעשה שימוש בכותרת `Report-To` כדי להגדיר קבוצות של נקודות קצה (endpoint) בעלות שם. משתמשת בכותרת `Reporting-Endpoints` כדי להגדיר נקודות קצה (endpoints) בעלות שם.
סוגי הדוחות שניתן להפיק באמצעות ה-API הזה
  • הוצאה משימוש
  • התערבות
  • תאונה
  • COOP/COEP
  • מדיניות אבטחת תוכן ברמה 3 (רמה 3 של CSP)
  • רישום של שגיאות רשת (NEL)
למידע נוסף על סוגי הדוחות בפוסט ב-Reporting API
ללא שינוי, למעט מ-Network Error Logging (NEL): הדבר לא נתמך ב-Reporting API החדש (v1).
היקף הדוח מקור.
הכותרת Report-To של מסמך משפיעה על מסמכים (דפים) אחרים מאותו מקור. השדה url בדוח עדיין משתנה בהתאם למסמך.
מסמך.
הכותרת Reporting-Endpoints של מסמך משפיעה רק על המסמך הזה. השדה url בדוח עדיין משתנה בהתאם למסמך.
בידוד דוחות (קיבוץ) מסמכים (דפים) או אתרים/מקורות שונים שמייצרים דוח בערך באותה שעה, ושיש להם אותה נקודת קצה לדיווח, יקובצו יחד: הם יישלחו באותה הודעה לנקודת הקצה לדיווח.
  • דוחות ממסמכים שונים (דפים) אף פעם לא נשלחים יחד. גם אם שני מסמכים (דפים) מאותו מקור יפיקו דוח בו-זמנית, עבור אותה נקודת קצה, הם לא יקובצו. זהו מנגנון לצמצום התקפות על פרטיות.
  • דוחות מאותו מסמך (דף) יכולים להישלח יחד.
תמיכה באיזון עומסים / עדיפויות כן לא

מפתחי נקודות קצה (endpoint): צפויה עלייה של תנועת הגולשים

אם הגדרתם שרת משלכם כנקודת קצה לדיווח, או אם אתם מפתחים או מתחזקים אוסף דוחות כשירות, אפשר לצפות לתנועה רבה יותר לנקודת הקצה הזו.

הסיבה לכך היא שלא מקובצים דוחות ב-Reporting API v1 כמו שהם ב-Reporting API v0. לכן, כשמפתחי אפליקציות יתחילו לעבור ל-Reporting API v1, מספר הדוחות יישארו דומות, אבל נפח הבקשות לשרת נקודת הקצה יגדל.

מפתחי אפליקציות: Migrate to Reporting-Endpoints (v1)

מה עליך לעשות?

יש כמה יתרונות לשימוש בגרסה החדשה של Reporting API (גרסה 1) ✅:

  • האותות של הדפדפן הם חיוביים. כלומר, צפויה תמיכה בדפדפנים שונים בגרסה 1 (בניגוד ל-v0 שנתמכת רק ב-Chrome קצה).
  • ה-API פחות נקי.
  • אנחנו מפתחים את הכלים בהתאם לגרסה החדשה של Reporting API (גרסה 1).

כדאי להביא בחשבון את הדברים הבאים:

  • אם באתר שלך כבר נעשה שימוש ב-Reporting API v0 עם הכותרת Report-To, יש לעבור אל Reporting API גרסה 1 (מידע נוסף זמין בשלבים להעברה). אם האתר כבר משתמש פונקציונליות של דיווח על הפרות של מדיניות Content-Security-Policy. השלבים הספציפיים להעברה לדיווח על CSP זמינים במאמר.
  • אם באתר שלכם עדיין לא נעשה שימוש ב-Reporting API ועכשיו אתם מוסיפים פונקציונליות של דיווח: להשתמש ב-Reporting API החדש (v1) (הכותרת Reporting-Endpoints). יש חריג אחד this: אם אתם צריכים להשתמש ב-Network Error Logging, השתמשו Report-To (v0). רישום של שגיאות רשת לא נתמכת כרגע ב-Reporting API v1. מנגנון חדש לרישום שגיאות רשת עד שיהיה זמין, צריך להשתמש ב-Reporting API v0. אם אתם צריכים רישום של שגיאות רשת לצד סוגי הדוחות האחרים, צריך להשתמש גם ב-Report-To (v0) וגם ב-Reporting-Endpoints (v1). v0 נותן לך Network Error Logging ו-v1 נותנת דוחות מכל הסוגים האחרים.

שלבי ההעברה

היעד שלכם בהעברה הזו הוא לא לאבד את הדוחות שהשתמשתם בהם בגרסה 0.

  1. שלב 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.

  2. שלב 2 (לעשות עכשיו): מוודאים שהכותרת Reporting-Endpoints מוגדרת לכל התשובות יכול ליצור דוחות.

    בגרסה 0 אפשר להגדיר נקודות קצה לדיווח רק בחלק מהתשובות ובמסמכים אחרים (דפים) במקור הזה ישתמשו בערך "סביבתי" נקודת הקצה. עם גרסה 1, בגלל ההבדל את ההיקף, צריך להגדיר את הכותרת Reporting-Endpoints בכל התשובות שעשויות ליצור דוחות.

  3. שלב 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. הדוחות האלה נקראים 'דוחות ברמה 2 של CSP' ולעשות לא מסתמכות על 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. שלב 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 (גרסה 0) כדי לקבל דוחות על הפרות של מדיניות COOP (הכותרת Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy) או מדיניות מסמך (הכותרת Document-Policy): אין צורך לשנות את כותרות המדיניות האלה עצמן במהלך ההעברה לדיווח על גרסה 1 של Reporting API. מה שצריך לעשות הוא לעבור מהכותרת הקודמת של Report-To לכותרת החדשה הכותרת Reporting-Endpoints.

אם אתם משתמשים בגרסה הקודמת של Reporting API (גרסה 0) כדי לקבל דוחות על הפרות מדיניות ל-CSP (הכותרת Content-Security-Policy), יכול להיות שיהיה צורך לבצע שינויים ב-Content-Security-Policy כחלק מ את המעבר ל-Reporting API החדש (גרסה 1).

העברה בסיסית

קוד מדור קודם (עם v0)
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
קוד חדש (קוד מעבר עם v0 לצד v1)
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" }] }

אם כבר יש פונקציונליות דיווח באתר שלך, אפשר להשאיר את Report-To באופן זמני בלבד (עד שרוב לקוחות Chrome ו-Edge עודכנו) כדי לא לאבד דוחות.

אם צריך רישום של שגיאות רשת ברשת, צריך להשאיר את Report-To עד להחלפה של Network Error Logging הופך לזמין.

קוד חדש (עם גרסה 1 בלבד)
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

כך הקוד שלך עשוי להיראות בעתיד, לאחר שרוב לקוחות Chrome ו-Edge יעודכנו ויתמכו ב-API v1.

הערה: בגרסה 1 עדיין אפשר לשלוח סוגי דוחות ספציפיים לנקודות קצה ספציפיות. אבל את/ה יכולה להיות כתובת URL אחת בלבד לכל נקודת קצה.

צפייה בכל הדפים

קוד מדור קודם (עם v0), לדוגמה עם Express
app.get("/", (request, response) => {
  response.set("Report-To", )
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

אם משתמשים בגרסה 0, אפשר להגדיר נקודות קצה לדיווח רק על תשובות מסוימות. המלצות אחרות מסמכים (דפים) במקור הזה משתמשים באופן אוטומטי בנקודות הקצה ברקע. כאן מגדירים נקודות קצה בשביל "/" משמשים לכל התשובות, לדוגמה page1.

קוד חדש (עם v1), לדוגמה עם Express
// 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(...)
});

עם v1, עליך להגדיר את הכותרת Reporting-Endpoints בכל של תגובות שעלולות להפיק דוחות.

העברה של דיווח CSP

קוד מדור קודם, עם report-uri בלבד
Content-Security-Policy: ...; report-uri https://reports.example/main

השימוש רק ב-report-uri לא נמצא יותר מומלץ. אם הקוד נראה כמו למעלה, מבצעים העברה. ראו דוגמאות לקוד חדש בהמשך (בירוק).

קוד משופר מדור קודם, עם report-uri והוראת report-to עם כותרת 'דוח אל' (גרסה 0)
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

עדיף: הקוד הזה משתמש ב-Report-to, התחליף החדש יותר ל- report-uri. הוא עדיין שומר את ה-report-uri לצורך תאימות לאחור. כמה הדפדפנים לא תומכים report-to אבל כן תמיכה report-uri

עם זאת, אולי יש מקום לשיפור: הקודים האלה משתמשים ב-Reporting API v0 (הכותרת Report-To). מעבר לגרסה 1: כאן אפשר לראות את 'קוד חדש' דוגמאות למטה (בירוק).

קוד חדש, עם report-uri והוראת report-to עם הכותרת Reporting-Endpoints (v1)
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

צריך להשאיר את ההוראה report-uri לצד ההוראה report-to עד להוראה report-to יש תמיכה בדפדפנים שונים. בדיקת תאימות הדפדפן טבלה.

אני רוצה להשאיר את Report-To לצד Reporting-Endpoints באופן זמני. לאחר רוב השימוש ב-Chrome וב-Edge מבקרים שדרגו ליותר מ-96 גרסאות דפדפן. ניתן להסיר את Report-To.

קריאה נוספת

תמונה ראשית (Hero) של Nine Koepfer / @enka80 מופעלת ביטול הפתיחה, נערכה. ברוב תודה לאיאן Clelland, Eiji Kitamura ו-Milica Mihajlija (הביקורות וההצעות שלהם בנושא הזה) מאמר.