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

גרסה 3.x של ה-API תושבת באוגוסט 2023

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

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

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

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

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

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

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

ציר הזמן

  • לפני 2022: גרסה 3.0 של ה-API הוצאה משימוש, גרסה 3.1 היא גרסה יציבה וגרסה 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, תצטרכו לבדוק את הקוד ולשים לב לשינויים הבאים.

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

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

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

דוגמה ל-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\"}"

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

דוגמה ל-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. כדי לוודא שהאפליקציות שלכם מוגדרות בצורה נכונה במהלך ההעברה ואחריה, השתמשו בגרסאות עדכניות (23.0 ואילך) של ערכות SDK של שפות שנתמכות ב-Looker. רוב ערכות ה-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 באוגוסט. כדי לעשות את זה, אתם יכולים להפעיל את האפשרות Deny API 3.x requests (דחיית בקשות API 3.x) בחלונית הניהול של התכונות מדור קודם.

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

export FF_DENY_API3=true

שאלות נפוצות

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

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

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

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

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

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

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

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

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