פתרון בעיות בסביבת התוספים של Looker

סביבת התוספים של Looker מאפשרת לכם ליצור אפליקציות ותרשימים בהתאמה אישית ב-JavaScript וב-TypeScript שפועלים בתוך Looker. התוספים פועלים ב-iframe בארגז חול (sandbox) ומקיימים אינטראקציה עם המכונה של Looker דרך Extension SDK. אם נתקלתם בבעיות בתוסף בהתאמה אישית – כמו דף ריק או הודעת שגיאה בתוך iframe, שגיאות JavaScript במסוף הדפדפן או שגיאות שיתוף משאבים בין מקורות (CORS), בקשות Looker API שנכשלו (קודי סטטוס 4xx או 5xx) או שגיאות בהגדרות של manifest.lkml – המסמך הזה יעזור לכם לפתור אותן.

דרישות מוקדמות ודרישות תצורה נפוצות

לפני שמתחילים לפתור בעיות, צריך לוודא שהסביבה, הפרויקט של LookML וחשבון המשתמש עומדים בדרישות להפעלת תוסף Looker:

  • סביבת התוספים מופעלת: אדמין ב-Looker צריך להפעיל את ההגדרה Extension Framework בקטע Admin > Platform > Extension Framework.
  • הגדרת פרויקט ומודל של LookML: כל תוסף דורש פרויקט של LookML שכולל את הרכיבים הבאים:
  • הרשאות מניפסט: ההצהרה application בקובץ manifest.lkml חייבת להגדיר באופן מפורש את כל entitlements שהתוסף דורש, כמו core_api_methods לקריאות ל-Looker API או external_api_urls לבקשות לדומיינים חיצוניים. תוסף לא יפעל בלי בלוק entitlements.
  • הרשאות משתמשים: למשתמשים צריכות להיות הרשאות לתוסף (כמו access_data,‏ explore או develop) לקבוצת מודלים שכוללת את מודל ה-LookML של התוסף. כדי לפתח תוסף, המפתחים צריכים הרשאות LookML develop.
  • כלי אבחון ופרטי סביבה: לפני שמתחילים לפתור את הבעיה, צריך להכין את הפרטים והכלים הבאים:
    • כתובת ה-URL של המכונה של Looker, שם הפרויקט של LookML והשם של application שמוצהר ב-manifest.lkml.
    • גישה לכלים למפתחים של דפדפן האינטרנט (הכרטיסיות Console ו-Network) במחשב הלקוח.
    • במהלך פיתוח מקומי, גישה לטרמינל שמריץ את שרת הפיתוח המקומי.
    • לשגיאות בחיבור לשרת 5xx בקריאות ל-Looker API, גישה ליומנים של מכונות Looker (looker.log במכונות שמתארחות אצל הלקוח, או ב-Logs Explorer ב-Cloud Logging במסוף Google Cloud למכונות Looker (Google Cloud core)).

עץ ניפוי באגים

כדי להתחיל לפתור בעיות בסביבת התוספים של Looker, אפשר להשתמש בעץ ההחלטות הבא:

בקטעים הבאים מתוארים התרחישים שבתרשים בפירוט רב יותר.

בדיקת המסוף ויומני הרשת של הדפדפן

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

בדיקה אם יש שגיאות במסוף הדפדפן

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

  1. ב-Looker, פותחים את הדף שבו התוסף נטען.
  2. לוחצים לחיצה ימנית במקום כלשהו בדף ובוחרים באפשרות בדיקה (או לוחצים על Control+Shift+I ב-Windows וב-Linux, או על Command+Option+I ב-macOS).
  3. בחלונית הכלים למפתחים, בוחרים בכרטיסייה מסוף.
  4. מרעננים את הדף כדי לתעד שגיאות שמתרחשות במהלך הטעינה הראשונית.
  5. בודקים אם יש הודעות שגיאה באדום במסוף:

בדיקת בקשות שנכשלו בכרטיסייה "רשת"

כדי לנתח בקשות HTTP שהתוסף שולח לחבילות JavaScript, לנכסים או לנקודות קצה ל-API, פועלים לפי השלבים הבאים:

  1. בחלונית הכלים למפתחים בדפדפן, לוחצים על הכרטיסייה רשת.
  2. מסמנים את התיבה Disable cache כדי שהדפדפן לא יטען משאבים ישנים מהמטמון.
  3. מרעננים את הדף שבו התוסף נטען.
  4. בודקים אם ברשימת הבקשות לאחזור מהרשת יש קודי סטטוס מסוג 4xx או 5xx, ובוחרים בקשה שנכשלה כדי לבדוק את הכרטיסיות כותרות, מטען ייעודי (payload) ותגובה:
    • ‫404 בחבילת התוספים (למשל bundle.js): מוודאים ששרת הפיתוח פועל ושהפרמטר url או file ב-manifest.lkml מדויק.
    • ‫401 או 403 בבקשת Looker API: בודקים את האימות, ההרשאות והזכאויות.
    • ‫400 או 422 בבקשת API: בודקים את הכרטיסיות Payload ו-Response כדי לזהות קובץ JSON בפורמט שגוי או פרמטרים לא תקינים של בקשה.
    • שגיאות בחיבור לשרת 5xx: שגיאות בצד השרת במכונה של Looker. כדי למצוא רשומות עם חותמות זמן תואמות, בודקים את looker.log במכונות אירוח בצד הלקוח או את Logs Explorer במסוף של מכונות Looker (Google Cloud core).

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

אימות המניפסט והגדרות הפרויקט

ההצהרה application בקובץ manifest.lkml של הפרויקט קובעת איך Looker טוען את התוסף ובאילו משאבים התוסף יכול להשתמש. הגדרות שגויות ב-manifest.lkml הן סיבה נפוצה לכשלים בטעינה וב-API:

  • בודקים את הפרמטר url או file: ב-Looker IDE, פותחים את הקובץ manifest.lkml של הפרויקט ובודקים את ההצהרה application:
    • הצהרת application חייבת לכלול פרמטר url או פרמטר file, אבל לא את שניהם.
    • במהלך הפיתוח המקומי: מוודאים שהפרמטר url תואם לפרוטוקול (http או https), לשם המארח, ליציאה ולנתיב המדויקים שמוצגים על ידי שרת הפיתוח המקומי (לדוגמה, https://localhost:8080/bundle.js).
    • בסביבת הייצור: מוודאים שעדכנתם את ההצהרה application מהנתיב url של סביבת הפיתוח המקומית לנתיב file של סביבת הייצור בפרויקט LookML (לדוגמה, file: "apps/bundle.js") או לכתובת ה-URL של החבילה בסביבת הייצור.
  • אימות ההרשאות של manifest.lkml: בודקים את הבלוק entitlements בהצהרה של application. תוסף לא יכול להשתמש במשאב של Looker או בדומיין חיצוני, אלא אם ההרשאה הזו מוצהרת באופן מפורש, באופן הבא:
    • ‫core_api_methods: צריך לציין כל שיטה של Looker API שהתוסף קורא לה (לדוגמה, core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • ‫external_api_urls: צריך לציין את כל הדומיינים החיצוניים שלא שייכים ל-Looker, שהתוסף שולח אליהם בקשות באופן ישיר או דרך שרת ה-proxy.
    • הרשאות נוספות: בודקים אם התוסף דורש את ההרשאות local_storage,‏ navigation,‏ new_window,‏ new_window_external_urls,‏ use_form_submit,‏ use_embeds,‏ use_downloads,‏ use_iframes,‏ use_clipboard,‏ oauth2_urls,‏ global_user_attributes או scoped_user_attributes.
  • אימות, אישור ופריסה: אחרי שעורכים את manifest.lkml, לוחצים על Validate LookML, מאשרים את השינויים ולוחצים על Deploy to Production כדי שההגדרה המעודכנת תיכנס לתוקף.

פתרון בעיות בסביבה ובשרת הפיתוח המקומיים

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

  • מוודאים ששרת הפיתוח פועל: בודקים את חלון הטרמינל שבו הפעלתם את שרת הפיתוח (לדוגמה, באמצעות yarn develop או npm start):
    • מוודאים שה-build עבר קומפילציה בלי שגיאות ומוצגת הודעת האזנה (כמו webpack compiled successfully או listening on localhost:8080).
    • אם השרת לא פועל, מפעילים אותו באמצעות yarn develop או npm start.
    • אם השרת נסגר בגלל שגיאת תחביר או שגיאה של תלות חסרה, פתרו את שגיאת הקוד או הריצו את yarn install (או npm install) כדי להתקין חבילות חסרות.
    • אם השרת נכשל בגלל התנגשות ביציאות (EADDRINUSE), צריך לעצור את התהליך האחר שמשתמש ביציאה הזו, או להגדיר את שרת הפיתוח ואת הפרמטר manifest.lkml url כך שישתמשו ביציאה אחרת.
  • פותחים את כתובת ה-URL של התוסף ישירות בדפדפן: מעתיקים את הערך url מ-manifest.lkml (לדוגמה, https://localhost:8080/bundle.js) ופותחים אותו בכרטיסייה חדשה בדפדפן:
    • אישור SSL בחתימה עצמית שלא נחשב מהימן: שרתי פיתוח מקומיים משתמשים לעיתים קרובות באישורי SSL בחתימה עצמית. אם בדפדפן מוצגת אזהרת אבטחה לגבי האישור, לוחצים על Advanced וממשיכים אל localhost כדי להגדיר את האישור כאמין בסשן של הדפדפן. עד שהאישור יהיה מהימן, הדפדפן יחסום את טעינת החבילה בתוך Looker iframe.
    • החיבור נדחה או נחסם: אם הדפדפן לא מצליח להגיע לכתובת ה-URL, ודאו שאין חומת אש מקומית או תוכנת אבטחה של נקודת קצה שחוסמת את החיבורים אל localhost ביציאה שהוגדרה.

פתרון בעיות שקשורות לרשת, ל-CORS ולמדיניות האבטחה

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

  • זיהוי שגיאות CORS במסוף הדפדפן: מחפשים הודעות שגיאה בכרטיסייה Console שמכילות את הכותרות Cross-Origin Resource Sharing,‏ CORS,‏ has been blocked by CORS policy או כותרות Access-Control-Allow-Origin חסרות.
  • הגדרת כותרות CORS של שרת פיתוח מקומי: אם אתם משתמשים ב-webpack-dev-server (או בכלי דומה לאיסוף חבילות), ודאו שההגדרה של devServer ב-webpack.config.js כוללת את הכותרת Access-Control-Allow-Origin: javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • הגדרת אירוח בסביבת ייצור וכותרות CORS של ממשקי API חיצוניים: אם התוסף טוען נכסים או מבקש נתונים משירות חיצוני (כמו Cloud Storage,‏ Amazon S3 או שרת בק-אנד בהתאמה אישית), צריך להגדיר את שירות האירוח כך שיחזיר את הכותרת Access-Control-Allow-Origin שמאפשרת את הדומיין של המכונה של Looker. צריך גם לוודא שאין שרת proxy או חומת אש ברשת שמסירים את כותרות ה-CORS מהתגובה, ושהדומיין החיצוני מופיע ב-external_api_urls ב-manifest.lkml.
  • בדיקת Content Security Policy (CSP) וטעינת תוספים משופרת: אם נתקלתם בהפרות של Content Security Policy בזמן טעינת תוסף, בדקו את ההגדרה טעינת תוספים משופרת בקטע ניהול > פלטפורמה > מסגרת תוספים.

פתרון בעיות שקשורות לאימות ולגישה ל-API

תוספים יוצרים אינטראקציה עם Looker API בשם המשתמש שמחובר לחשבון באמצעות Extension SDK. אם הקריאות ל-API נכשלות עם קודי הסטטוס 401 Unauthorized או 403 Forbidden בכרטיסייה Network, צריך לבדוק את הדברים הבאים:

  • הבחנה בין שגיאות 401 לשגיאות 403:
    • ‫401 Unauthorized: הבקשה לא אומתה. השגיאה הזו בדרך כלל מתרחשת אם ערכת ה-SDK של התוסף לא אותחלה כמו שצריך, או אם התוסף ניסה לבצע קריאה ל-API לפני שערכת ה-SDK השלימה את לחיצת היד לאימות.
    • ‫403 Forbidden: הבקשה אומתה, אבל למשתמש המחובר אין את ההרשאות הנדרשות ב-Looker, או שה-manifest.lkml של התוסף לא כולל את השיטה שנקראה ב-core_api_methods.
  • אימות תפקידי משתמשים והרשאות: בקטע Admin > Users ובקטע Admin > Roles, בודקים את התפקידים, קבוצות ההרשאות וקבוצות המודלים שהוקצו למשתמש המחובר:
    • מוודאים שלמשתמש יש הרשאות להשתמש בתוסף, כולל access_data (וגם explore או develop לפי הצורך) לקבוצת מודלים שמכילה את מודל ה-LookML של התוסף וכל מודל שהתוסף שולח אליו שאילתות.
    • מוודאים שהתפקיד של המשתמש כולל את ההרשאות הספציפיות שנדרשות לכל נקודת קצה ל-Looker API שהתוסף קורא לה.
  • מוודאים שההקשר של ה-SDK מוכן לפני ששולחים קריאה ל-API: מוודאים שקוד התוסף ממתין להפעלת ההקשר של Extension SDK לפני שהוא מפעיל שיטות API.

פתרון בעיות ב-Extension SDK וביחסי התלות

בעיות בהתקנה של חבילת npm או Yarn, או רכיבים חסרים של ספק ה-SDK, יכולים למנוע מהתוסף לעבור הידור (compilation) או להתחבר ל-Looker:

  • מוודאים שהמודול של Node.js הותקן: במסוף, עוברים לתיקיית השורש של פרויקט התוסף ובודקים את התיקייה node_modules:
    1. אם node_modules חסר או שיחסי התלות נראים פגומים, מחקו את הספרייה node_modules ואת קובץ הנעילה (yarn.lock או package-lock.json).
    2. אופציונלי: אם התקנת החבילה נכשלת שוב ושוב, נקו את המטמון של מנהל החבילות (לדוגמה, הריצו את npm cache clean --force).
    3. מוודאים שגרסת Node.js שמותקנת תואמת לדרישות הפרויקט, ואז מריצים את yarn install או את npm install כדי לבצע התקנה נקייה.
  • בודקים את ההפעלה של ExtensionProvider: פותחים את קובץ נקודת הכניסה הראשי של התוסף (כמו App.js או index.js) ומוודאים ש-<ExtensionProvider> (מיובא מ-@looker/extension-sdk-react) כולל את רכיבי האפליקציה שצריכים את ההקשר של Looker SDK: javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); אם <ExtensionProvider> חסר או אם מיקמתם אותו אחרי רכיבים שקוראים ל-SDK, רכיבי צאצא לא יכולים לגשת להקשר של ה-SDK.

פתרון שגיאות לוגיות ושגיאות JavaScript בזמן ריצה

אם ההגדרות, שרת הפיתוח, ההרשאות והגדרת ה-SDK של התוסף תקינים, יכול להיות שהבעיה היא שגיאת זמן ריצה בקוד ה-JavaScript או ה-TypeScript המותאם אישית של התוסף:

  • ניתוח דוחות הקריסה במסוף: בכרטיסייה Console בדפדפן, מאתרים את הודעת השגיאה האדומה ולוחצים על החץ להרחבה כדי לראות את דוח הקריסה המלא. השורות העליונות בדוח הקריסות מזהות את הקובץ ואת מספר השורה בקוד המקור שבהם אירעה השגיאה. לוחצים על הקישור לקובץ (לדוגמה, MyComponent.js:42) כדי לעבור ישירות לשורה הזו בכרטיסייה מקורות.
  • בודקים אם יש ערכים לא מוגדרים או ערכי null: בשגיאות כמו TypeError: Cannot read properties of undefined, מוודאים שתגובות מה-API האסינכרוני או המאפיינים סיימו להיטען לפני שהקוד קורא מאפיינים בתצוגת עץ. הוסיפו בדיקות הגנה (כמו if (myObject && myObject.property) או שרשור אופציונלי myObject?.property).
  • אימות הפורמטים של התגובות מה-API: ודאו שהקוד שלכם מטפל במבנה הנתונים בפועל שמוחזר על ידי קריאות ל-Looker API (לדוגמה, אימות אם מטען ייעודי (payload) של תגובה הוא אובייקט או מערך לפני קריאה לשיטות של מערכים).
  • ניפוי באגים באמצעות נקודות עצירה (breakpoint) ורישום ביומן: בכרטיסייה Sources בדפדפן, מגדירים נקודות עצירה לפני השורה שנכשלה כדי להשהות את ההפעלה ולבדוק את ערכי המשתנים בזמן אמת, או מוסיפים הצהרות console.log() כדי לעקוב אחרי תהליך ההפעלה.

אימות התאימות של גרסת Looker

עדכונים או שינויים משמעותיים בתכונות של Looker עשויים לדרוש גרסה תואמת של Looker Extension SDK:

  1. בודקים את הגרסה של @looker/extension-sdk (וגם של @looker/extension-sdk-react, אם משתמשים בה) בקובץ package.json של פרויקט התוסף.
  2. בממשק האינטרנט של Looker, בודקים את גרסת ההפצה הנוכחית של המכונה בקטע Help > About או בקטע Admin > General > Settings.
  3. משווים בין גרסת ההפצה של Looker לבין הערות התאימות במסמכי התיעוד של @looker/extension-sdk.
  4. אם המכונה של Looker שודרגה לאחרונה והתוסף משתמש ב-SDK מיושן, או אם התוסף משתמש בתכונה חדשה יותר של SDK שלא נתמכת בגרסה קודמת של Looker, צריך לעדכן את חבילת ה-SDK לגרסה תואמת: bash npm install @looker/extension-sdk@latest אחרי שמעדכנים את החבילה, מתקינים מחדש את יחסי התלות ומפעילים מחדש את שרת הפיתוח.

איסוף נתוני אבחון

אם הבעיה לא נפתרה אחרי שניסיתם את השלבים לפתרון בעיות, אספו את המידע הבא לפני שאתם פונים לתמיכה:

  1. פרטי המכונה והפרויקט ב-Looker:
    • כתובת ה-URL של המכונה ב-Looker (לדוגמה, instance_name.looker.com).
    • גרסת ההפצה של Looker.
    • שם הפרויקט של LookML שמכיל את התוסף ואת השם של application ב-manifest.lkml.
  2. הגדרת התוסף ופרטי ה-SDK:
    • עותק או צילום מסך של ההצהרה של application בקובץ manifest.lkml.
    • הגרסה של @looker/extension-sdk שצוינה ב-package.json.
    • אם התוסף פועל משרת פיתוח מקומי (url) או פרוס בסביבת הייצור (file).
  3. יומני שגיאות וצילומי מסך:
    • צילומי מסך או הטקסט המלא של השגיאות מהכרטיסיות Console ו-Network בדפדפן (כולל כותרות הבקשות ומטעני הייעוד של התגובות לבקשות 4xx או 5xx שנכשלו).
    • אם קריאות ל-API מחזירות באופן עקבי שגיאות בחיבור לשרת 5xx, קטעי יומן תואמים מ-looker.log (למכונות באירוח בצד הלקוח) או מ-Logs Explorer ב-Logging (למכונות של Looker (Google Cloud core)).
  4. סיכום של פתרון הבעיות והשלבים לשחזור הבעיה:
    • סיכום של שלבי פתרון הבעיות שכבר ביצעתם והתוצאות שלהם.
    • השלבים המדויקים לשחזור הבעיה, או דוגמה מינימלית לשחזור אם אתם חושדים שיש בעיה בסביבת התוספים של Looker או ב-Extension SDK.

פנייה לתמיכה

אם ביצעתם את כל השלבים הקודמים והבעיה עדיין לא נפתרה: