הוצאה משימוש של Looker API 3.x

‫API 3.x יושבת באוגוסט 2023

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

בעקבות ההשקה של API 4.0 ב-Looker 22.4, הודענו על הוצאה משימוש של API 3.1, בנוסף ל-API 3.0 שכבר הוצא משימוש.

החל מההודעה על הוצאה משימוש שפרסמנו ביוני 2022, גם API בגרסה 3.1 וגם API בגרסה 3.0, שנקראים ביחד גרסה 3.x, נמצאים במצב הוצאה משימוש. גרסאות API‏ 3.x יושבתו החל מגרסה 23.14 של Looker באוגוסט 2023.

השדרוג הזה יופעל בהדרגה במופעים שמארחת Looker במהלך שעות התחזוקה בין 14 באוגוסט ל-24 באוגוסט. לכן, כל המקרים של אירוח Looker מחייבים שדרוג של האפליקציות לשימוש בנקודות קצה של API בגרסה 4.0 במקום בנקודות קצה של API בגרסה 3.x לפני 14 באוגוסט 2023. כל הפונקציות שמסתמכות על נקודות קצה בגרסה 3.x יפסיקו לפעול אחרי השינוי הזה.

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

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

לקוחות שלא מצליחים לבצע את המעבר ל-API 4.0 צריכים לפנות אל התמיכה של Looker.

ציר הזמן

  • לפני 2022: ממשק API 3.0 הוצא משימוש, ממשק API 3.1 הוא בסטטוס יציב וממשק API 4.0 הוא בסטטוס בטא
  • מרץ 2022: API 4.0 עובר לסטטוס יציב וזמין לכלל המשתמשים ב-Looker 22.4
  • יוני 2022: הודעה על הוצאה משימוש של API 3.1
  • אוגוסט 2023: נשבית את API 3.x ב-Looker

למי מיועד המאמר הזה?

המאמר הזה מיועד למי שמשתמש ב-Looker API דרך ערכות SDK שנתמכות על ידי Looker, ערכות SDK שנתמכות על ידי הקהילה או ה-API עצמו. כדאי להמשיך לקרוא כדי לקבל מידע על שינויים שעלולים לגרום לכשלים באפליקציה, וגם

מה עליי לעשות?

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

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

פרטי המיגרציה של API 4.0

שינוי הקוד כך שיפנה ל-API החדש

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

### API 3.1 ###
GET https://myinstance.looker.com/api/3.1/users/5877

### API 4.0 ###
GET https://myinstance.looker.com/api/4.0/users/5877

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

### API 3.1 ###
import looker_sdk
sdk = looker_sdk.init31()

### API 4.0 ###
import looker_sdk
sdk = looker_sdk.init40()

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

החלפות של נקודות קצה ב-API 3.x

כדי לשמור על עקביות בטרמינולוגיה בין Looker API לבין ממשק המשתמש של Looker, ב-API 4.0 הוחלפו כמה נקודות קצה שהוצאו משימוש ב-API 3.x בנקודות קצה שוות ערך או משופרות, שמפורטות בהמשך:

שם נקודות הקצה של 'מרחב' השתנה. במקום זאת, צריך להשתמש בנקודות קצה (endpoint) של Folder שהן מילים נרדפות.

דוגמה ל-Python SDK

    #####################
    ##### API 3 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_space(
      body=mdls.CreateSpace(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.space(space_id="555")

    # Change name of existing Folder
    response = sdk.update_space(
      space_id="555",
      body=mdls.UpdateSpace(
        name="My Updated Folder"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_folder(
      body=mdls.CreateFolder(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.folder(folder_id="555")

    # Change name of existing Folder
    response = sdk.update_folder(
      space_id="555",
      body=mdls.UpdateFolder(
        name="My Updated Folder"
      )
    )

דוגמה ל-cURL

    #####################
    ##### API 3 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/spaces/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/3.1/spaces/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/folders/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/4.0/folders/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"

הוסרו נקודות קצה של דף הבית. במקום זאת, צריך להשתמש בנקודות הקצה של הפונקציונליות המורחבת 'לוח'.

דוגמה ל-Python SDK

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    response = sdk.homepage(homepage_id=1348)

    # Update displayed title of Board item
    response = sdk.update_homepage_item(
      homepage_item_id=86,
      body=mdls.WriteHomepageItem(
        custom_title="Volume 3"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    response = sdk.board(board_id=1348)

    # Update displayed title of Board item
    response = sdk.update_board_item(
      board_item_id=86,
      body=mdls.WriteBoardItem(
        custom_title="Volume 3"
      )
    )

דוגמה ל-cURL

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/homepages/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/3.1/homepage_items/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/boards/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/4.0/boards/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"

‫API 4.0: שינויים משמעותיים בסוגי שדות המזהים

ב-API 4.0, סוגי השדות של חלק משדות המזהים עודכנו ממספרים למחרוזות. אפשר להשתמש בכלי שלנו להשוואה בין מאמרי העזרה של ה-API כדי לראות אילו שדות מזהים השתנו בין גרסה 3.1 לגרסה 4.0. כדי לוודא שהאפליקציות שלכם יתאימו לסוגים במהלך ההעברה ואחריה, צריך להשתמש בערכות SDK של שפות שנתמכות ב-Looker (גרסה 23.0 ואילך). רוב ערכות ה-SDK בשפות שנתמכות על ידי הקהילה, כולל Kotlin, ‏ Swift, ‏ R, ‏ C# ו-Go, כבר פועלות עם הסוגים המעודכנים.

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

השוואת API 4.0

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

השבתה או הפעלה של API 3.x באמצעות כפתור החלפת מצב של תכונה מדור קודם

ללקוחות עם אירוח Looker שמשתמשים ב-Looker 23.6,‏ 23.8,‏ 23.10 ו-23.12, לאדמינים יש כרגע אפשרות להשבית את כל הקריאות לנקודות קצה של API 3. כך תוכלו לבדוק את המופע שלכם כדי לוודא שאף שירות או אפליקציה משולבים לא יפסיקו לפעול לפני תאריך היעד – 14 באוגוסט. כדי לעשות זאת, אפשר להפעיל את האפשרות 'דחיית בקשות API מגרסה 3.x' בלוח הבקרה של תכונות מדור קודם.

לקוחות עם אירוח עצמי שמשתמשים ב-Looker בגרסאות 23.6,‏ 23.8,‏ 23.10 ו-23.12 יכולים להריץ את פקודת ה-Shell הבאה לפני הפעלת Looker כדי להוסיף משתנה סביבתי שיגרום להצגת המתג 'דחיית בקשות API בגרסה 3.x' (הערה: אחרי הרצת הפקודה, עדיין תצטרכו להעביר את המתג בחלונית 'תכונות מדור קודם' בממשק המשתמש של Looker כדי להפסיק קריאות ל-API בגרסה 3):

export FF_DENY_API3=true

שאלות נפוצות

אני לא בטוח/ה אם מתבצעות קריאות ל-API בגרסה 3.x במופע שלי. איפה אפשר למצוא את המידע הזה?

החל מ-Looker 23.8, בעמודה Source (מקור) בחלונית Admin (אדמין) > Queries (שאילתות) מוצגת עכשיו בצורה נכונה גרסת ה-API ‏(v3 או v4) של שאילתות שמופעלות מ-Looker API. המידע הזה לא יכלול מידע על משימות של אדמינים או מפתחים, כמו יצירת משתמשים או פיתוח LookML או משימות Git.

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

אני מארח מופע משלי. האם צריך לשדרג עד 14 באוגוסט 2023?

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

המופע שלי מתארח ב-Looker, אבל הוא חלק מתוכנית ESR. האם צריך לשדרג עד 14 באוגוסט 2023?

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

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

לקוחות שלא מצליחים לבצע את המעבר ל-API 4.0 צריכים לפנות אל התמיכה של Looker.