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

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

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

מידע: כדי לקרוא מידע נוסף על טיפול בחריגים ב-JavaScript, אפשר לעיין במאמר בנושא הוראות try...catch.

סוגי השגיאות

הסוגים והסיבות לשגיאות שמשתמשים עשויים להיתקל בהן במהלך השימוש במחבר שלכם בדרך כלל נחלקים לאחת משלוש הקטגוריות הבאות:

  1. שגיאות פנימיות במחבר
  2. connector external errors
  3. שגיאות ב-Looker Studio

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

שגיאה פנימית במחבר

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

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

שגיאה חיצונית במחבר

שגיאות חיצוניות של מחברים מתרחשות אחרי הפעלת המחבר. לדוגמה, כשבקשת getData() לשלושה שדות מחזירה נתונים רק לשני שדות. למרות שהמחבר סיים את ההרצה, הוא לא ענה על הבקשה מ-Looker Studio. בדיקות יסודיות יכולות למנוע את השגיאות האלה.

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

שגיאה ב-Looker Studio

שגיאות ב-Looker Studio הן שגיאות שלא קשורות לקוד של המחבר. לדוגמה, אם משתמש מנסה להשתמש בתרשים מסוג פעולות על ציר הזמן עם מקור נתונים שלא כולל מאפיין של תאריך/שעה.

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

הצגת הודעות שגיאה

הצגת פרטי השגיאה בהתאם לסטטוס האדמין

כשמחבר מחזיר שגיאה, הודעת השגיאה מוצגת ב-Looker Studio בהתאם לסטטוס האדמין של המשתמש.

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

הצגת שגיאות למשתמשים

כברירת מחדל, רק אדמינים של מחברים יכולים לראות את פרטי השגיאה. זה עוזר למנוע חשיפה לא מכוונת של מידע רגיש, כמו מפתח API במעקב אחר מחסנית. כדי להציג הודעות שגיאה למשתמשים שאין להם הרשאות אדמין, משתמשים ב-newUserError() משירות Looker Studio Apps Script.

דוגמה:

try {
  // API request that can be malformed.
  getDataFromAPI();
} catch (e) {
  DataStudioApp.createCommunityConnector()
      .newUserError()
      .setDebugText('Error fetching data from API. Exception details: ' + e)
      .setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
      .throwException();

}

בדוגמה הזו, setText() מגדיר את הטקסט שיוצג לכל המשתמשים, ואילו setDebugText() מגדיר את הטקסט שיוצג רק למשתמשים עם הרשאת אדמין.

שיטות מומלצות לטיפול בשגיאות במחברים

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

  • ניסיון כושל לאחזור כתובת URL (שגיאות זמניות, פסק זמן)
  • אין נתונים זמינים לתקופה המבוקשת
  • אי אפשר לנתח או לעצב נתונים מממשק ה-API
  • טוקנים של הרשאה בוטלו

טיפול בשגיאות שניתנות לתיקון

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

טיפול בשגיאות

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

איך מציגים שגיאות למשתמשים

תיעוד שגיאות ב-Stackdriver

משתמשים ב-Stackdriver כדי לרשום ביומן שגיאות והודעות אחרות. כך תוכלו להבין שגיאות, לנפות באגים ולגלות חריגים שלא טופלו.

מידע נוסף על Stackdriver Error Reporting, על הפעלת רישום חריגים (exception) בסקריפט ועל זיהוי משתמשים בטוח למטרות ניפוי באגים זמין במאמר שימוש ב-Stackdriver Logging.

הוצא משימוש: שימוש בקידומת DS_USER: להודעות שגיאה בטוחות

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

בדוגמאות הבאות יש מקרה שבו הודעת שגיאה תוצג למשתמשים שאינם אדמינים, ומקרה אחר שבו הודעת שגיאה תוצג רק למשתמשים שהם אדמינים:

data-studio/errors.gs
// Admin and non-admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('DS_USER:This will be shown to admin & non-admin.');
}

// Only admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('This message will only be shown to admin users');
}