ניהול מחזור החיים של API

בדף הזה מוסבר על התכונות של Cloud Endpoints API שקשורות לניהול גרסאות, ומוצגות שיטות מומלצות לניהול גרסאות ולבניית שלבי ביניים של Cloud Endpoints API. המידע בדף הזה רלוונטי לממשקי API שמשתמשים במפרט OpenAPI. לממשקי API שמשתמשים ב-Cloud Endpoints Frameworks בסביבה הרגילה של App Engine, אפשר לעיין במאמרים טיפול בניהול גרסאות של API: Java או טיפול בניהול גרסאות של API: Python.

מומלץ לפעול לפי אותם עקרונות בסיסיים ש-Google משתמשת בהם לניהול גרסאות של API ולהעברת שירותים לשלב ההכנה:

  • לפני שמפעילים את הגרסה הראשונית, צריך לכלול את השורות הבאות בקובץ התצורה של OpenAPI:

    • מגדירים את מספר הגרסה בשדה info.version. מומלץ להשתמש במחרוזת גרסה שכוללת גרסה ראשית וגרסת משנה, לדוגמה, 1.0.
    • מגדירים את השדה basePath כך שיכלול את מספר הגרסה הראשית. מומלץ להשתמש בנתיב בסיס בפורמט של האות v ואחריה מספר הגרסה הראשית, לדוגמה, /v1.

  • כשצריך לבצע שינוי שתואם לאחור, כמו הוספת שיטה חדשה, מגדילים את מספר הגרסה המשנית (1.2,‏ 1.3 וכו') בשדה info.version ומבצעים פריסה מחדש. פרטים נוספים זמינים במאמר בנושא ניהול גרסאות של API.

  • אם אתם צריכים לשנות שיטה קיימת שגורמת לשבירת קוד הלקוח, אתם צריכים ליצור עותק של קובץ התצורה של OpenAPI ולבצע את השינויים הבאים:

    • להגדיל את מספר הגרסה הראשית (2.0,‏ 3.0 וכו') בשדה info.version .
    • מגדילים את מספר הגרסה הראשית (/v2,‏ /v3 וכו') בשדה basePath.

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

  • הטמעה של כל הגרסאות הראשיות של ה-API בקצה העורפי (backend) יחיד. ההמלצה הזו:

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

  • כדאי להעביר את ה-API לסביבת ביניים בפרויקט נפרד Google Cloud לפני שפורסים אותו בפרויקט הייצור Google Cloud . פרטים נוספים מופיעים במאמר בנושא שירותי הכנה.

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

תכונות של ניהול גרסאות ב-Cloud Endpoints API

ל-Extensible Service Proxy (ESP) יש אפשרות לנהל כמה גרסאות ראשיות של ה-API בו-זמנית בפרויקט ובקצה העורפי יחידים, כל עוד אין חפיפה בנתיבי ה-API. Google Cloud לדוגמה:

http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo

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

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

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

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

דוגמה למחזור החיים של API

בקטע הזה מתואר תהליך התפתחות טיפוסי של שירות.

גרסה 1

בתחילה אתם פורסים את גרסה 1 של שירות My Awesome Echo API. ה-API מוגש מ-my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. בתרשימים וביומנים שבקטע נקודות קצה > שירותים, מוצגת כל התנועה ב-1.0.

גרסה 1.1

הלקוחות מבקשים תכונה חדשה, אז אתם מוסיפים שיטה חדשה. בקובץ התצורה של OpenAPI, מוסיפים את השיטה החדשה ומגדילים את הערך בשדה info.version ל-1.1. מגדילים את מספר הגרסה המשנית כי השינוי הזה לא גורם לבעיות בקוד של הלקוח. אתם פורסים את השינוי ובודקים אותו בסביבת Staging כדי לוודא שהוא פועל.

לאחר מכן פורסים את הגדרות ה-OpenAPI ואת העורף של ה-API בסביבת הייצור. ה-API עדיין מוגש מ-my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, אבל עכשיו אפשר לשלוח בקשות ל-method החדש. מכיוון שלא שיניתם את הממשק לשיטות הישנות, הלקוחות לא צריכים לשנות ולפרוס מחדש את הלקוחות שלהם. הלקוחות יכולים להמשיך לשלוח בקשות לשיטה הישנה כמו קודם.

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

גרסה 2.0

עם הזמן, אתם מבינים שאתם צריכים לבצע שינוי בשיטה קיימת שלא תואם לאחור. כדי לא לשבור את קוד הלקוח של הלקוחות, אתם מחליטים לשמור על שתי גרסאות של ה-API. משאירים את השיטה הישנה כמו שהיא ומטמיעים את הגרסה החדשה של השיטה. יוצרים עוד קובץ תצורה של OpenAPI לגרסה 2.0, ומגדירים שהגרסה החדשה תוגש מ-my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. קובץ התצורה המקורי של OpenAPI עדיין מצביע על הגרסה הישנה של השיטה, ואילו קובץ התצורה החדש של OpenAPI מצביע על הגרסה החדשה של השיטה.

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

אחרי הפריסה, בדף Endpoints > Services אפשר לראות שתי גרסאות של ה-API שמוצגות, ולבדוק את נפח התנועה בכל גרסה. לקוחות בגרסה 1 יכולים להמשיך להתקשר אל /v1, אבל הם יכולים גם להתקשר אל /v2 כדי להשתמש בגרסה החדשה של השיטה. האופן שבו מטפלים בניהול גרסאות בקוד הקצה העורפי תלוי במסגרת ה-API שבה משתמשים. דוגמה לשימוש ב-servlets זמינה במאמר Endpoints & Java with multiple versions sample.

השבתת גרסה 1

עם הזמן, כשהלקוחות יעברו לגרסה 2 ותראו שכל התנועה לגרסה 1 נעצרה, תוכלו להפסיק את ההצגה שלה. כדי להסיר את גרסה 1 של ה-API, פורסים רק את קובץ התצורה של OpenAPI בגרסה 2 ופורסים מחדש את הקצה העורפי. עכשיו אפשר להסיר בבטחה את הקוד שהטמיע את גרסה 1 מהקצה העורפי. ‫Endpoints > Services שומר את הנתונים ההיסטוריים מגרסה 1.x.

שירותי Staging

כשיטה מומלצת, כדאי להכין עדכונים לשירות Endpoints כדי שתוכלו לבדוק את השירות לפני שהוא מגיע ללקוחות שלכם. מומלץ גם ליצור פרויקטGoogle Cloud נפרד כדי להכין את השירות להשקה, כך שהוא יהיה מבודד מהייצור. לדוגמה, המכסות של Google בדרך כלל משותפות בין המשאבים בפרויקט. לכן, אם תשימו את שירות ה-staging באותו פרויקט כמו שירות הייצור, לולאת for שפועלת בצורה שגויה, למשל, עלולה לגרום להשבתה בשירות הייצור.

מומלץ לתת לפרויקט שם שברור ממנו שהוא מיועד לסביבת Staging. Google Cloud אחת מהאסטרטגיות הנפוצות למתן שמות היא להשתמש באותו שם כמו שם פרויקט הייצור Google Cloud , אבל עם -staging בסוף. אפשר גם להוסיף את התווית -prod לפרויקטים של סביבת ייצור, כדי להבהיר שהפרויקט מכיל שירותים של סביבת ייצור.

שמות השירותים ב- Google Cloud צריכים להיות ייחודיים. מכיוון שאתם מציינים את שם השירות בקובץ התצורה של OpenAPI, אתם צריכים לשמור קבצים נפרדים של הגדרות API לפרויקטים של שלבי הביניים והייצור, או להשתמש בקבוצה אחת של קבצים של הגדרות API ולפתח תהליך שבו אתם משנים את שם השירות כך שיתאים לשם הפרויקט שאתם פורסים בו.

המאמרים הבאים