פתרון בעיות ב-Looker API

בדף הזה מפורטות שיטות לפתרון בעיות שאתם עלולים להיתקל בהן ב-Looker API:

לא ניתן להגיע לנקודת קצה ל-API

אם אי אפשר להגיע לנקודת קצה ל-API:

אימות פרטי הכניסה ל-API

אם אי אפשר להגיע לנקודת הקצה של Looker API, קודם צריך לוודא שפרטי הכניסה ל-API נכונים.

אם אתם משתמשים במופע מקורי של Looker, כדי לראות את פרטי הכניסה של ה-API:

  1. ב-Looker, ניגשים אל חלונית האדמין על ידי בחירה באפשרות אדמין בחלונית הניווט הימנית.
  2. בחלונית הימנית של הדף ניהול, גוללים למטה ולוחצים על משתמשים.
  3. מחפשים את שם המשתמש ברשימת המשתמשים ולוחצים עליו כדי לערוך את דף המשתמש.
  4. לוחצים על Edit API Keys (עריכת מפתחות API). תוכלו לראות את מזהה הלקוח, וללחוץ על סמל העין כדי לראות את הסוד של הלקוח לכל מפתח API שהגדרתם. מוודאים שפרטי הכניסה של ה-API זהים לפרטי הכניסה שבהם אתם משתמשים בסקריפט.

אם אתם משתמשים במופע Looker (Google Cloud core), כדי לראות את פרטי הכניסה שלכם ל-API:

  1. ב-Looker, לוחצים על סמל המשתמש ובוחרים באפשרות חשבון כדי לגשת אל דף החשבון.
  2. בדף החשבון, בקטע אימות, לוחצים על הלחצן ניהול של מפתחות ה-API. ייפתח הדף API Keys.
  3. בדף API Keys אפשר לראות את כל מפתחות ה-API. לכל מפתח API מוצג מזהה הלקוח, ואפשר ללחוץ על הסמל הצגת הסוד כדי לראות את הסוד של הלקוח לכל מפתח API שהגדרתם. מוודאים שפרטי הכניסה ל-API זהים לפרטי הכניסה שבהם אתם משתמשים בסקריפט.

אימות כתובת ה-URL של ה-API

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

אדמינים ב-Looker יכולים לראות את כתובת ה-URL של מארח ה-API בהגדרות האדמין של ה-API (תיאור מפורט יותר מופיע בדף התיעוד הגדרות אדמין – API). כדי לראות את כתובת ה-URL של מארח ה-API:

  1. לוחצים על סמל התפריט הראשי של Looker‏ ובוחרים באפשרות אדמין כדי לפתוח את החלונית אדמין.
  2. לוחצים על API בחלונית Admin (אדמין).

  3. צפייה בכתובת ה-URL של מארח ה-API.

    אם השדה API Host URL ריק, המכונה של Looker משתמשת בפורמט ברירת המחדל:

    https://<instance_name>.cloud.looker.com:<port>

כדי לבדוק את כתובת ה-URL של מארח ה-API:

  1. פותחים דפדפן ואז פותחים את מסוף הדפדפן.

  2. מזינים את כתובת ה-URL של מארח ה-API ואחריה /alive. לדוגמה, אם כתובת ה-URL של מארח ה-API היא https://company.cloud.looker.com, מזינים:

    https://company.cloud.looker.com/alive

    אם השדה כתובת ה-URL של מארח ה-API ריק, צריך להשתמש בכתובת ה-URL של ה-API שמוגדרת כברירת מחדל. לדוגמה, במקרים של מופעים שמתארחים ב-Google Cloud, ב-Microsoft Azure ובמופעים שמתארחים ב-Amazon Web Services ‏ (AWS) ושנוצרו בתאריך 07/07/2020 ואילך, נתיב ברירת המחדל של Looker API משתמש ביציאה 443:

    https://<instance_name>.cloud.looker.com:443/alive

    במקרים שבהם מופעלים מופעים ב-AWS שנוצרו לפני 7 ביולי 2020, נתיב ברירת המחדל של Looker API משתמש ביציאה 19999:

    https://<instance_name>.cloud.looker.com:19999/alive

אם כתובת ה-URL של מארח ה-API נכונה, כתובת ה-URL הזו תוביל לדף אינטרנט ריק ולא לדף שגיאה.

אפשר גם לוודא שהגעתם לממשק ה-API על ידי עיון בתגובת הרשת במסוף הדפדפן. תגובת הרשת צריכה להיות 200.

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

אימות יציאת ה-API

אם הבדיקות הקודמות נכשלות ויש לכם פריסת Looker באירוח בצד הלקוח, יכול להיות שצריך לפתוח את יציאת ה-API בתשתית הרשת.

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

  • קובצי Proxy
  • מאזני עומסים
  • חומות אש

אימות כתובת ה-URL של הקריאה ל-API

צריך לוודא שאתם משתמשים בכתובת ה-URL הנכונה לקריאה ל-API. הפורמט של כתובת URL של נקודת קצה ל-API הוא:

<API Host URL>/api/<API version>/<API call>

אם משתמשים בכתובת ה-URL המארחת של ה-API שמוגדרת כברירת מחדל, הפורמט של נקודת קצה ל-API הוא:

https://<instance_name>:<port>/api/<API version>/<API call>

אפשר לקבל את פורמט כתובת ה-URL של נקודות קצה של API מ-API Explorer או ממסמכי התיעוד של API Reference.

לדוגמה, בהפניה ל-API 4.0 מופיע נתיב יחסי כזה לנקודת הקצה Get All Running Queries:

/api/4.0/running_queries

לכן, כתובת ה-URL המלאה של נקודת הקצה ל-API עבור נקודת הקצה Get All Running Queries במופע docsexamples.dev.looker.com Looker תהיה:

https://docsexamples.dev.looker.com:443/api/4.0/running_queries

תוצאת ה-API היא טקסט חסר משמעות

אם ה-API מחזיר תשובה של טקסט מבולבל, סביר להניח שאתם רואים את התוכן הבינארי של קובץ PDF,‏ PNG או JPG. יש ספריות HTTP REST שמניחות שתגובות API יהיו קובצי טקסט, ולכן סוגים אחרים של קבצים מוצגים כטקסט בינארי.

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

קריאות ל-API לא מגיבות

אם אתם מצליחים לפתוח את API Explorer אבל קריאות ה-API לא מגיבות, צריך לוודא שההגדרה API Host URL של מופע Looker מוגדרת בצורה נכונה. אדמינים ב-Looker יכולים לראות את כתובת ה-URL של מארח ה-API בהגדרות האדמין של ה-API ב-Looker (כפי שמתואר בדף התיעוד הגדרות אדמין – API).

שגיאות של קידוד לא תקין

אם מופיעה שגיאת קידוד כשמנסים לבצע קריאה ל-API, יכול להיות שצריך להגדיר את הקידוד המתאים Content-Type בכותרת במהלך הבקשה. התקנים של פרוטוקול HTTP מחייבים שכל בקשת POST,‏ PUT או PATCH תכיל כותרת Content-Type. מכיוון ש-Looker API משתמש ב-JSON בכל מקום, צריך להגדיר את הכותרת Content-Type ל-application/json.

שימו לב: שימוש ב-Looker SDK יטפל בבעיה הזו באופן אוטומטי.

שגיאות מסוג Method Not Found

אם מופיעה שגיאה מסוג Method Not Found (השיטה לא נמצאה), כמו method not found: all_looks(), הדבר הראשון שצריך לבדוק הוא גרסת ה-API. יש כמה קריאות ל-API שהן חדשות בגרסה 4.0 של API או שהוסרו בגרסה 4.0 של API. רשימת העדכונים מופיעה בהודעה Looker API 4.0 זמין לכולם.

שגיאות מסוג Bad Request ‏ (400)

שגיאה מסוג 400 Bad Request מציינת שהנתונים שסופקו בקריאה ל-API לא מזוהים. הגורם לבעיה הוא לרוב קובץ JSON פגום או לא תקין, אולי שגיאת ניתוח. ברוב המקרים, שגיאות 400 כבר עברו אימות, ולכן הודעת התגובה לשגיאה תספק מידע ספציפי יותר על השגיאה.

שגיאות 'אין הרשאה' (401)

שגיאה 401 Unauthorized בקריאה ל-API מציינת שהאימות של הקריאה ל-API לא בוצע כמו שצריך. פרטים נוספים לפתרון בעיות מופיעים במאמר איך פותרים שגיאות 401? מאמר קהילתי.

שגיאות Forbidden (אסור) ‏(403)

ממשק Looker API לא מחזיר שגיאות 403 בכל פעם שמשתמש מנסה לגשת לאובייקט של LookML או לתוכן אחר שאין לו הרשאה לגשת אליו. החזרת שגיאת 403 במקום שגיאת 404 יכולה, במקרים מסוימים, לאמת את קיומו של אובייקט מסוים של Explore, לוח בקרה או LookML, כשבעל האובייקט מעדיף שלא ידעו על כך. כדי למנוע את זה, Looker מחזיר 404 במקרים האלה, והשגיאה הנלווית בממשק המשתמש של Looker היא: 'לא ניתן למצוא את הדף שביקשת'. הוא לא קיים או שאין לך הרשאה לצפות בו".

מספר היציאה וכתובת ה-URL המשויכת שדרכה אפשר לגשת ל-API עשויים להיות שונים, בהתאם לסביבה שבה מתארח מופע Looker ולהגדרה של מופע Looker. אם משתמשים במספר יציאה שגוי, יכול להיות שתוצג שגיאה 403. לדוגמה, אם מופע Looker שלכם מוגדר עם יציאת ה-API שמוגדרת כברירת מחדל 443, התחברות אל https://mycompany.looker.com/api/4.0/login במקום אל https://mycompany.looker.com:443/api/4.0/login תחזיר שגיאה 403. במקרים של אירועים שמתארחים אצל הלקוח, אפשר לקרוא מידע נוסף על אפשרויות ההפעלה של Looker שבהן אפשר להגדיר את יציאת ה-API.

זה יכול לקרות גם כשמשתמשים בגרסה מיושנת של Ruby SDK gem. חשוב לוודא שהתכונות האלה מעודכנות. אפשר לבדוק בכתובת https://rubygems.org/gems/looker-sdk.

זה יכול לקרות גם אם לא כוללים את החלק /api/<version number>/ של כתובת ה-URL. במקרה כזה, אם משתמש ינסה להתחבר אל https://mycompany.looker.com:443/login, הוא יראה תגובה מסוג 403.

שגיאות 'לא נמצא' (404)

שגיאה 404 Not Found היא שגיאת ברירת המחדל אם משהו משתבש, בדרך כלל בעניינים כמו הרשאות. הודעת התגובה לשגיאת 404 מספקת מידע מינימלי, אם בכלל. התנהגות כזו היא מכוונת, כי שגיאות מסוג 404 מוצגות לאנשים עם פרטי כניסה שגויים או הרשאות לא מספיקות. מערכת Looker לא רוצה לספק מידע ספציפי בהודעות תגובה מסוג 404, כי אפשר להשתמש במידע הזה כדי למפות את 'שטח התקיפה' של Looker API.

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

  • https://<your-looker-hostname>:<port>/api/4.0/login

אם אתם משתמשים ב-API של Swagger codegen או ב-Looker SDK, ודאו שהערך של base_url נכון:

  • עבור לקוח Swagger codegen, הערך של base_url צריך להיות:

    • https://<your-looker-hostname>:<port>/api/4.0/

  • ביישומים של Looker SDK שמשתמשים ב-looker.ini, הערך של api_version צריך להיות 4.0, והערך של base_url צריך להיות זהה לכתובת ה-URL של Looker instance API בפורמט https://<your-looker-hostname>:<port>. קובץ looker.ini לדוגמה:

    # api_version should be 4.0
api_version=4.0
base_url=https://<your-looker-hostname>:<port>

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

שגיאות מסוג Method Not Allowed (405)‎

שגיאת 405 Method Not Allowed מציינת שהשרת מכיר את שיטת הבקשה, אבל משאב היעד לא תומך בשיטה הזו.

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

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

שגיאות Conflict ‏ (409)

קוד הסטטוס של התשובה 409 Conflict מציין שיש התנגשות בין הבקשה לבין המצב הנוכחי של משאב היעד.

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

יכול להיות שתיתקלו בשגיאה הזו ב-Looker כשאתם מנסים לבצע checkout של ענף git חדש באמצעות ה-API, או כשאתם משתמשים בנקודות קצה כמו create_group() או create_dashboard(). במקרים כאלה, צריך לבדוק אם האובייקט שניסיתם ליצור כבר קיים.

שגיאות אימות (422)

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

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

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

זוהי דוגמה לתשובה:

{
  "message": "Validation Failed",
  "errors": [
    {
    "field": "dialect",
    "code": "missing_field",
    "message": "This field is required.",
    "documentation_url": "http://docs.looker.com/"
    },
    {
    "field": "db_timezone",
    "code": "invalid",
    "message": "Must specify a database timezone when user timezones are activated.",
    "documentation_url": "http://docs.looker.com/"
    }
  ],
    ...

במקרה הזה, בקריאה ל-API חסר השדה הנדרש dialect, וגם הערך שצוין בשדה db_timezone לא תקין.

שגיאות Too Many Requests ‏ (429)

קוד סטטוס התגובה 429 Too Many Requests מציין שהמשתמש שלח יותר מדי בקשות בפרק זמן מסוים ('הגבלת קצב'). מידע נוסף על מדיניות הגבלת הקצב של Looker זמין בפוסט בקהילת Looker בנושא Is there a limit to the number of API requests you can send at one time? (האם יש הגבלה על מספר בקשות ה-API שאפשר לשלוח בו-זמנית?).

שגיאות Internal Server Error (500)

קוד התגובה 500 Internal Server Error מציין שהשרת נתקל בתנאי לא צפוי שמנע ממנו למלא את הבקשה.

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