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

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

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

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

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

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

  1. שגיאות פנימיות של המחבר
  2. שגיאות חיצוניות של המחבר
  3. שגיאות ב-Looker Studio

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

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

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

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

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

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

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

שגיאה ב-Looker Studio

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

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

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

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

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

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

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

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

דוגמה:

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 Logging תוכלו לקרוא מידע נוסף על התכונה 'דיווח על שגיאות ב-Stackdriver'. תוכלו לקרוא איך מפעילים רישום חריגים בסקריפט ואיך לזהות משתמשים בבטחה למטרות ניפוי באגים.

הוצא משימוש: יש להשתמש בקידומת 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');
}