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

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

Maud Nalpas

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

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

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

הערה: גרסת Reporting API הקודמת נקראת Reporting API v0. ה-Reporting API החדש נקרא Reporting API v1.

סיכום

מפתחי אתרים

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

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

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

v0 (קודם)

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

גרסה 1 (חדש)

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

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

מה לא משתנה

• הפורמט והמבנה של הדוחות לא השתנו.
• הבקשה שנשלחת מהדפדפן לנקודת הקצה (endpoint) נשארת בקשת 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.	ללא שינוי, למעט מ-Network Error Logging (NEL): תכונה זו לא נתמכת ב-Reporting API החדש (v1).
היקף הדוח	מקור. הכותרת Report-To של מסמך משפיעה על מסמכים (דפים) אחרים מאותו מקור. השדה url בדוח עדיין משתנה לפי מסמך.	מסמך. הכותרת Reporting-Endpoints של מסמך משפיעה רק על המסמך הזה. השדה url בדוח עדיין משתנה לפי מסמך.
בידוד דוחות (קיבוץ)	מסמכים (דפים) או אתרים/מקורות שונים שיוצרים דוח בערך באותו זמן ויש להם את אותו נקודת קצה לדיווח יקובצו יחד: הם יישלחו באותה הודעה לנקודת הקצה לדיווח.	דוחות ממסמכים (דפים) שונים אף פעם לא נשלחים יחד. גם אם שני מסמכים (דפים) מאותו מקור יוצרים דוח באותו זמן, לאותו נקודת קצה, הם לא יקובצו יחד. זהו מנגנון לצמצום התקפות על הפרטיות. דוחות מאותו מסמך (דף) יכולים להישלח יחד.
תמיכה באיזון עומסים / עדיפויות	כן	לא

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

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

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

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

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

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

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

שלבי ההעברה

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

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

1. שלב 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. שלב 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): אין צורך לשנות את כותרות המדיניות האלה בעצמן במהלך המעבר ל-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(...)
});

ב-v1, צריך להגדיר את הכותרת 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 על הביקורות וההצעות שלהם לגבי המאמר הזה.