דף זה תורגם על ידי Cloud Translation API.

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

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

Maud Nalpas

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

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

סיכום

מפתחי אתרים

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

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

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

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

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

בהמשך תוכלו למצוא פרטים וקוד לדוגמה.

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

אזהרה: אם משתמשים ברישום של שגיאות רשת, המשיכו להשתמש ב-Report-To (v0) כי ב-Reporting API אין תמיכה ב-Reporting API v1.

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

הדגמה (דמו) וקוד

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

ההבדלים בין v0 לבין v1

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

הפלטפורמה של ה-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 בכותרות אחרות מפנים לקבוצות האלה של נקודות הקצה.

v1 (חדש)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

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

היקף הדוח שונה.

v0 (מדור קודם)

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

v1 (חדש)

ב-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 הזה	הוצאה משימוש התערבות תאונה COOP/COEP Content-Security-Policy Level 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, מספר הדוחות ימשיך להיות דומה, אבל נפח הבקשות לשרת נקודות הקצה יגדל.

מפתחי אפליקציות: העברה אל `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.
שלב 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).

העברה בסיסית

קוד מדור קודם (עם 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 עד שהחלפה של 'רישום שגיאות רשת' תהיה זמינה.

קוד חדש (עם v1 בלבד)

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(...)
});

ב-v0 אפשר להגדיר נקודות קצה לדיווח רק בחלק מהתשובות. מסמכים (דפים) אחרים מהמקור משתמשים באופן אוטומטי בנקודות הקצה האלה ברקע. כאן, נקודות הקצה שמוגדרות ל-"/" משמשות לכל התגובות. למשל, 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

קוד מדור קודם, עם URI בלבד

Content-Security-Policy: ...; report-uri https://reports.example/main

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

קוד טוב יותר מדור קודם, עם report-uri והוראת report-to עם הכותרת Report-To (v0)

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-to, אבל כן תומכים ב-report-uri.

עדיין יש מקום לשיפור: הקודים האלה משתמשים ב-Reporting API v0 (הכותרת Report-To). מעבר ל-v1: עיינו בדוגמאות של 'קוד חדש' שבהמשך (בירוק).

קוד חדש, עם 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.

קריאה נוספת

מעקב אחר אפליקציית האינטרנט באמצעות Reporting API (פוסט ראשי ב-Reporting API)
מפרט: מדור קודם של Reporting API (גרסה 0)
מפרט: גרסה חדשה של Reporting API (גרסה 1)

תמונה ראשית (Hero) מאת Nine Koepfer / @enka80 ב-UnFlood, נערכה. תודה רבה לאיאן קלילנד, אייג'י קיטמורה ומיליקה מיהג'ליג'ה על הביקורות וההצעות שלהם במאמר הזה.