שימוש ב-API Explorer

‫Looker API Explorer הוא תוסף – אפליקציית אינטרנט שנבנית באמצעות רכיבי Looker – שמפותח באמצעות סביבת התוספים של Looker ומופץ דרך Looker Marketplace.

‫API Explorer מספק את הנכסים הבאים לשימוש עם Looker API:

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

אפשר גם להשתמש בתכונה sudo as another user של Looker כדי לשלוח בקשות API כמשתמש אחר, וכך לאבחן בעיות גישה.

התקנת API Explorer

‫API Explorer זמין ב-Marketplace של Looker.

לפני שמתקינים את API Explorer מ-Marketplace, אדמין ב-Looker צריך להפעיל את התכונה Extension Framework.

כדי להתקין אפליקציות מ-Marketplace, כמו התוסף API Explorer, צריך לקבל את ההרשאות develop,‏ manage_models ו-deploy. אחרי שמתקינים את API Explorer, כל משתמש עם הרשאה access_data לפחות במודל extension_api_explorer יכול להשתמש ב-API Explorer. כל משתמש יכול לראות את כל נקודות הקצה של ה-API ב-API Explorer, אבל יכול להפעיל רק את אלה שההרשאות שלו מאפשרות.

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

אם האדמין שלכם ב-Looker לא הפעיל את האפשרות התקנה אוטומטית, תצטרכו להתקין את API Explorer מ-Looker Marketplace.

הוראות להתקנת תוסף מ-Looker Marketplace מופיעות בדף התיעוד בנושא שימוש ב-Looker Marketplace. כדי לוודא שתמיד יש לכם את הגרסה העדכנית ביותר של API Explorer, אתם יכולים להיכנס אל Looker Marketplace, ללחוץ על Manage ואז על Update לצד התוסף.

הפעלת API Explorer

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

בדף הבית של API Explorer אפשר לבצע את המשימות הבאות:

  1. משתמשים בתפריט הנפתח לבחירת שפה ב-SDK כדי לבחור את שפת התכנות שבה יוצגו ב-API Explorer הצהרות על שיטות וסוגים של API ותוצאות קוד. כברירת מחדל, הבורר מוגדר ל-Python בטעינה הראשונית. אם בוחרים באפשרות All (הכול) בתפריט לבחירת שפה, ב-API Explorer מוצג תצוגה עם כרטיסיות לכל שפה נתמכת.

  2. בתפריט הנפתח של הגרסה, בוחרים גרסה של ה-API:

    • ‫4.0 – נוכחית

  3. לוחצים על הלחצן השוואת מפרטים כדי לפתוח את דף ההשוואה של גרסאות ה-API.

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

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

  5. בוחרים בכרטיסייה Methods כדי להציג את הקטגוריות של ה-method של ה-API. אפשר להרחיב או לכווץ קטגוריה של שיטות כדי לראות את השיטות הנפרדות בקטגוריה.

  6. בוחרים בכרטיסייה Types כדי להציג סוגי API. הסוגים לא מחולקים לקטגוריות ומוצגים בסדר אלפביתי.

  7. לוחצים על הלחצן תפריט ראשי כדי להסתיר או להציג את חלונית הניווט של API Explorer.

איך רואים את התיעוד של שיטת API וסוג ה-API

כשבוחרים קטגוריית שיטות בכרטיסייה שיטה, קטגוריית השיטות מתרחבת ומוצגות כל השיטות שכלולות בה.

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

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

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

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

הצהרות על שיטות וסוגים

‫API Explorer מעבד את השיטה וההצהרות על הסוגים של ה-SDK בשפת ה-SDK שנבחרה בתפריט הנפתח של בורר שפת ה-SDK. אם בחרתם באפשרות All (הכול) בכלי לבחירת שפה ב-SDK, ההצהרות על השיטה והסוג יוצגו בכל השפות הנתמכות ב-SDK, כשהן מופרדות באמצעות כרטיסיות.

דוגמאות ל-SDK

במאגר sdk-codegen Looker יש תיקייה שמכילה דוגמאות ל-Looker SDK. אם בsdk-codegenמאגר יש דוגמאות לשיטה, בדף API Explorer של השיטה יוצג הקטע SDK Examples עם קישורים לדוגמאות.

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

יכול להיות שיוצגו גם דוגמאות של Ruby ו-Java, למרות שאלה לא שפות SDK.

קובצי עזר

בקטע References של כל method וסוג, יש קישורים לדפים של API Explorer לכל method או סוג שהופנו אליהם מה-method או מהסוג המקוריים.

שימוש ב-Run It כדי לבקש ולהציג קריאות ל-API

ב-API Explorer יש לחצן Run It (הפעלת הבקשה) שפותח חלונית שממנה אפשר לשלוח בקשות לקריאות ל-API ולהציג את התגובות במגוון פורמטים נתמכים.

כשלוחצים על הלחצן Run It (הפעלת הבקשה), מוצגת בכלי API Explorer הכרטיסייה Request (בקשה), שבה אפשר לספק את נתוני הקלט לשיטת ה-API.

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

בכל פעם ששיטת ה-API יכולה לשנות נתונים (לכל קריאת REST שהיא POST, ‏ PATCH, ‏ UPDATE או DELETE), מופיעה תיבת הסימון לאישור שינוי הנתונים, וצריך לסמן אותה כדי להפעיל את הבקשה.

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

בנוסף, בכרטיסייה קוד מוצג תחביר הקריאה ל-SDK שנבחר בתפריט הנפתח של בורר השפות. אם בבורר השפות של ה-SDK מוגדרת האפשרות All (הכול), תחביר הקריאה ל-SDK מוצג בכל השפות הנתמכות של ה-SDK, כשהוא מחולק לכרטיסיות.

סוגי התצוגה של התגובות

התשובות ב-API Explorer כוללות סוג MIME שמשמש לקביעת אופן הצגת התוצאות.

נתונים בטבלה בפורמט CSV ופורמטים אחרים

עבור נתוני CSV ו-JSON, ‏ Looker מבצע בדיקת צורה כדי לקבוע אם הנתונים עומדים בקריטריונים של טבלה. אם Looker קובע שנתוני המטען הייעודי הם טבלאיים, תצוגת ברירת המחדל של התגובה היא רשת נתונים.

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

JSON

מטענים ייעודיים (payloads) מסוג JSON יכולים להיות טבלאיים, ובמקרה כזה הם יוצגו ברשת. כותרות העמודות של שאילתת LookML מוצגות בפורמט <view_name>.<field_name>, במקום להציג את התווית של השדה.

במטענים ייעודיים (payloads) מורכבים של JSON, התצוגה של הרשת מושמטת ומוצג רק ה-JSON הגולמי.

‫PNG ו-JPEG

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

דוגמה להורדה של קובץ PNG.

SVG

חלק מנקודות הקצה של Looker מחזירות SVG, שגם נתמך ישירות. זוהי דוגמה לנקודת הקצה content_thumbnail בפורמט SVG, שמחזירה תמונה ממוזערת מופשטת של לוח בקרה.

דוגמה להורדה של SVG.

HTML

בקשות שמחזירות קוד מקור HTML מציגות את קוד המקור של ה-HTML בכרטיסייה תגובה.

טקסט

בקשות שמחזירות SQL או פורמטים אחרים שמסווגים כטקסט פשוט לפי סוג MIME מוצגות כטקסט פשוט בכרטיסייה תשובה.

השוואה בין גרסאות API

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

  1. בוחרים את גרסת הבסיס של ה-API ואת גרסת ה-API שרוצים להשוות לגרסת הבסיס.

  2. בוחרים את אפשרויות ה-API שרוצים לכלול בהשוואה כדי לסנן את השיטות כך שיוצגו רק אלה שיש בהן הבדלים באפשרויות שבחרתם. האפשרויות הן:

    • חסרים – מוצגות כל השיטות שקיימות בגרסה אחת של ה-API וחסרות בגרסה השנייה.
    • סטטוס – מוצגות כל השיטות שבהן הסטטוס של השיטה השתנה. לדוגמה, שיטה שבה הסטטוס השתנה מ-beta ל-stable.
    • פרמטרים – מוצגות כל השיטות שבהן השתנה פרמטר אחד או יותר של השיטה.
    • סוג – מוצגים סוגים שיש להם מאפיינים חדשים, שהוסרו או שהשתנו.
    • גוף – מוצגים שינויים בפרמטרים של הגוף.
    • תגובה – מוצגות כל השיטות שבהן חל שינוי בתגובה של השיטה.

  3. בדף ההשוואה מוצג מספר השיטות שבהן יש הבדל, ורשימה של השיטות שבהן יש הבדל.

  4. בוחרים שיטה כדי להרחיב אותה, ובדף ההשוואה מוצג ההבדל בין הגרסאות של השיטה.