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

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

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 v0 למנגנון החדש.

הדגמה וקוד

• אתר הדגמה: Reporting API חדש (גרסה 1)
• קוד לאתר ההדגמה

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

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

• ממשק ה-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 תומכים באותם סוגי דוחות, עם חריג אחד: גרסה 1 לא תומכת בדוחות שגיאות ברשת. מידע נוסף זמין בשלבי ההעברה.
• גרסה v0 לא נתמכת בדפדפנים שונים, ולא תהיה תמיכה כזו בעתיד. יש סיכוי גבוה יותר שגרסה v1 תיתמך בדפדפנים שונים בעתיד.

מה לא משתנה

• הפורמט והמבנה של הדוחות לא השתנו.
• הבקשה שנשלחת מהדפדפן לנקודת הקצה נשארת בקשת POST של Content-type application/reports+json.
• מיפוי של נקודות קצה מסוימות לסוגים מסוימים של דוחות נתמך בגרסה v0 ובגרסה v1.
• התפקיד של נקודת הקצה default לא השתנה.

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

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

מפתחי נקודות קצה: צפוי עומס תנועה גדול יותר

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

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

מפתחי אפליקציות: מעבר ל-Reporting-Endpoints (גרסה 1)

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

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

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

חשוב לזכור:

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

שלבים בהעברה

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

1. שלב 1 (לביצוע עכשיו): משתמשים בשני הכותרים: Report-To (גרסה 0) ו-Reporting-Endpoints (גרסה 1).

   היתרונות של המינוי:

   • דוחות מלקוחות חדשים יותר של Chrome ו-Edge הודות ל-Reporting-Endpoints (גרסה 1).
   • דוחות מלקוחות ישנים יותר של Chrome ו-Edge הודות ל-Report-To (גרסה 0).

   בדפדפנים שתומכים ב-Reporting-Endpoints נעשה שימוש ב-Reporting-Endpoints, ובדפדפנים שלא תומכים ב-Reporting-Endpoints נעשה שימוש ב-Report-To. הפורמט של הבקשה והדוח זהה בגרסה v0 ובגרסה v1.

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

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

3. שלב 3 (מתחילים מאוחר יותר): אחרי שכל המשתמשים או רובם יעברו לגרסאות מאוחרות יותר של Chrome או Edge (גרסה 96 ואילך), מסירים את Report-To (גרסה 0) ומשאירים רק את 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), ויש כמה יתרונות לשימוש בגישה השנייה. בפרט, הוא מאפשר לכם להשתמש בדרך אחת להגדרת דיווח לכל סוגי הדוחות, וגם להגדיר נקודת קצה כללית (כי לכל בקשות הדוחות שנוצרות באמצעות 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 (גרסה 0) ומשאירים רק את Reporting-Endpoints. כדאי להשאיר את האפשרות הזו מופעלת כדי להמשיך לקבל דוחות לגבי דפדפנים שתומכים רק בה.report-uri

דוגמאות קוד לשלבים האלה מופיעות במאמר העברה של דוחות CSP.

מיגרציה: קוד לדוגמה

סקירה כללית

אם אתם משתמשים בגרסה הקודמת של Reporting API‏ (v0) כדי לקבל דוחות על הפרות של COOP (Cross-Origin-Opener-Policy header), ‏ COEP (Cross-Origin-Embedder-Policy) או מדיניות מסמכים (Document-Policy header): אתם לא צריכים לשנות את כותרות המדיניות האלה כשאתם עוברים ל-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"

שימו לב: בגרסה 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‏ (v0)
• מפרט: Reporting API חדש (גרסה 1)

תודה רבה לאיאן קללנד, לאייג'י קיטאמורה ולמיליקה מיחאיליה על הביקורות וההצעות שלהם בנוגע למאמר הזה.