טיפול בניהול גרסאות של API

בדף הזה מוסבר איך ליצור גרסאות של ה-API ואיך לפרוס לכמה גרסאות.

המלצות לניהול גרסאות API

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

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

בטבלה הבאה מוצגות גרסאות של API לעורף שמועברות מדור לדור לגרסאות שונות של אפליקציות App Engine.

גרסת האפליקציה גרסת ה-API של ה-Backend
1
  • ‫v1 --> v1 (2) --> v1 (n)
2
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
3
  • v1 (n)
  • v2 (n)
  • גרסה 3 --> גרסה 3 (2) --> גרסה 3 (n)

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

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

פריסה למספר גרסאות של אפליקציות

כשפורסים את ה-API של ה-Backend, פורסים אותו למזהה הפרויקט של פרויקטGoogle Cloud שיצרתם עבור ה-API, וצריך גם לציין את הגרסה של App Engine שפורסים אליה. מציינים את גרסת אפליקציית App Engine ברכיב <version> של הקובץ /WEB-INF/appengine-web.xml. גרסת האפליקציה ב-App Engine לא זהה למספר הגרסה של ה-API של ה-Backend, שאתם מציינים במאפיין version של ההערה @Api.

apiversions

כפי שמוצג באיור הקודם, אפשר לפרוס כמה גרסאות API לאותה גרסת App Engine. בנוסף, יכולות להיות הרבה גרסאות של App Engine לאפליקציה.

גישה לגרסאות API שנפרסו לגרסת הגשה

הגרסה הראשונה של App Engine שפורסים אליה את ה-API היא הגרסה שמוצגת למשתמשים. הגרסה הזו פועלת בכתובת ה-URL‏ http://YOUR_PROJECT_ID.appspot.com, כאשר YOUR_PROJECT_ID מייצג את מזהה הפרויקט Google Cloud. אפשר לגשת לכל גרסאות ה-API שנפרסו לגרסת היישום הזו ב-App Engine באמצעות כתובת ה-URL הזו.

גרסת ההצגה נשארת זהה עד שמשנים אותה באופן מפורש בGoogle Cloud מסוף.

גישה לגרסאות API שנפרסו לגרסת אפליקציה שלא משרתת תנועה

אם אתם צריכים לגשת לגרסאות API שלא נפרסו לגרסת App Engine שמוצגת כרגע, אתם יכולים להשתמש בכתובת URL ספציפית לגרסה, בדומה לכתובת הבאה:

https://VERSION-dot-YOUR_PROJECT_ID.appspot.com

מחליפים את VERSION בגרסה של App Engine ואת YOUR_PROJECT_ID במזהה הפרויקט ב- Google Cloud . לדוגמה, נניח שגרסת ההגשה של App Engine היא 1, אבל אתם רוצים לגשת לגרסת API שפרוסה בגרסה 2. כתובת ה-URL שבה צריך להשתמש: https://2-dot-YOUR_PROJECT_ID.appspot.com.

פרטים נוספים מופיעים במאמרי העזרה של App Engine.

גישה לגרסאות API שנפרסו בשירותים שאינם שירותי הפעלה (לשעבר מודולים)

אם אתם צריכים לגשת לגרסאות API שלא נפרסו בשירות ברירת המחדל של App Engine, אתם יכולים להשתמש בכתובת URL ספציפית לשירות באמצעות תחביר הנקודה באופן הבא:

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...

פרטים נוספים מופיעים במאמרי העזרה של App Engine.