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

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

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

Maud Nalpas

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

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

סיכום

מפתחי אתרים

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

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

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

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

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

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

רישום שגיאות ברשת ביומן

זהירות: אם אתם משתמשים ברישום שגיאות ברשת, עליכם להמשיך להשתמש ב-Report-To (גרסה 0), כי רישום שגיאות ברשת לא נתמך ב-Reporting API v1.

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

הדגמה וקוד

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

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

v1 (חדש)

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

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

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

v0 (קודם)

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

v1 (חדש)

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

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

מה לא משתנה

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

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

	Reporting API מדור קודם (גרסה 0) כותרת `Report-To`	Reporting API חדש (גרסה 1) `Reporting-Endpoints` כותרת
תמיכה בדפדפנים	Chrome מגרסה 69 ואילך ו-Edge מגרסה 69 ואילך.	Chrome מגרסה 96 ואילך ו-Edge מגרסה 96 ואילך. יש תמיכה גם ב-Firefox. דפדפן Safari לא מתנגד. אותות מהדפדפן
נקודות קצה	שליחת דוחות לכל אחד ממספר אוספי הדוחות (מספר כתובות URL מוגדרות לכל קבוצת נקודות קצה).	שליחת דוחות לאוספים ספציפיים של דוחות (רק כתובת URL אחת מוגדרת לכל נקודת קצה).
ממשק API	משתמשים בכותרת `Report-To` כדי להגדיר קבוצות של נקודות קצה בעלות שם.	הכותרת `Reporting-Endpoints` משמשת להגדרת נקודות קצה בעלות שם.
סוגי הדוחות שאפשר ליצור באמצעות ה-API הזה	הפסקת תמיכה התערבות תאונה COOP/COEP Content-Security-Policy ברמה 3 (CSP ברמה 3) רישום שגיאות ברשת ביומן (NEL) _{מידע נוסף על סוגי הדוחות זמין בפוסט בנושא Reporting API.}	ללא שינוי, מלבד יומני שגיאות רשת (NEL): האפשרות הזו לא נתמכת ב-Reporting API החדש (גרסה 1).
היקף הדוח	מקור. הכותרת `Report-To` של מסמך משפיעה על מסמכים (דפים) אחרים מהמקור הזה. השדה `url` בדוח עדיין משתנה לפי מסמך.	מסמך. הכותרת `Reporting-Endpoints` של המסמך משפיעה רק על המסמך הזה. השדה `url` בדוח עדיין משתנה לפי מסמך.
בידוד דוחות (אוסף)	מסמכים (דפים) או אתרים/מקורות שונים שיוצרים דוח בערך באותו זמן ויש להם את אותו נקודת קצה לדיווח יקובצו יחד: הם יישלחו באותה הודעה לנקודת הקצה לדיווח.	דוחות ממסמכים (דפים) שונים אף פעם לא נשלחים יחד. גם אם שני מסמכים (דפים) מאותו מקור יוצרים דוח באותו זמן, לאותו נקודת קצה, הם לא יקובצו יחד. זהו מנגנון לצמצום התקפות על הפרטיות. אפשר לשלוח יחד דוחות מאותו מסמך (דף).
תמיכה באינטראקציה עם מאזני עומסים או עם תעדוף	כן	לא

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

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

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

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

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

יש כמה יתרונות לשימוש ב-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). יש חריג אחד: אם אתם צריכים להשתמש ביומן שגיאות ברשת, צריך להשתמש ב-Report-To (v0). כרגע אין תמיכה בדיווח ביומן על שגיאות ברשת ב-Reporting API v1. אנחנו נגבש מנגנון חדש לרישום שגיאות ברשת ביומן⏤עד שהוא יהיה זמין, תוכלו להשתמש ב-Reporting API v0. אם אתם צריכים רישום ביומן של שגיאות ברשת יחד עם סוגים אחרים של דוחות, צריך להשתמש גם ב-Report-To (v0) וגם ב-Reporting-Endpoints (v1). v0 מאפשר לכם לקבל רישום ביומן של שגיאות ברשת, ו-v1 מאפשר לכם לקבל דוחות של כל הסוגים האחרים.

שלבי ההעברה

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

שלב 1 (עכשיו): משתמשים בשני הכותרות: Report-To (v0) ו-Reporting-Endpoints (v1).

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

בגרסה 0, אפשר להגדיר נקודות קצה לדיווח בתגובות מסוימות בלבד, ומסמכים אחרים (דפים) במקור הזה ישתמשו בנקודת הקצה 'הסביבתית' הזו. בגרסה 1, בגלל ההבדל בהיקף, צריך להגדיר את הכותרת 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), ולגישה השנייה יש כמה יתרונות. באופן ספציפי, הוא מאפשר לכם להשתמש בדרך אחת כדי להגדיר דיווח לכל סוגי הדוחות, וגם להגדיר נקודת קצה גנרית (כי לכל בקשות הדוחות שנוצרות דרך 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 כדי להמשיך לקבל דוחות בדפדפנים שתומכים רק בו.

דוגמאות לקוד של השלבים האלה מפורטות במאמר העברת דיווח של שותף עצמאי לדיווח (CSP).

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

סקירה כללית

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

קוד חדש (עם 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(...)
});

בגרסה 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(...)
});

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

העברת דיווח של ספקי שירות מנוהלים

קוד מדור קודם, עם report-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-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.

קריאה נוספת

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

תודה רבה ל-Ian Clelland, ל-Eiji Kitamura ול-Milica Mihajlija על הביקורות וההצעות שלהם לגבי המאמר הזה.