הוספת גרסאות ל-API

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

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

מידע נוסף ושיטות מומלצות זמינים במאמר ניהול מחזור החיים של API.

שינויים שתואמים לגרסאות קודמות

כשמבצעים שינויים ב-API שתואמים לאחור לקוד לקוח קיים, מומלץ להגדיל את מספר הגרסה המשנית של ה-API לפני שמפעילים את הגרסה החדשה. למרות ש-Cloud Endpoints מפעיל רק גרסה משנית אחת של API בכל פעם, הגרפים והיומנים בEndpoints > Services מציגים את מספר הגרסה. אם מגדילים את מספר הגרסה המשנית לפני הפריסה, התרשימים והיומנים מספקים היסטוריה מתויגת של הפריסות.

כדי להגדיל את מספר הגרסה המשנית:

  1. ב-openapi.yaml, מגדילים את מספר הגרסה המשנית של השדה info.version. לדוגמה, אם הגרסה הנוכחית היא 1.1, צריך להגדיר את info.version ל-1.2:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. משתמשים ב-Google Cloud CLI כדי לפרוס את הגדרות ה-API:

    gcloud endpoints services deploy openapi.yaml

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

שינויים שאינם תואמים לאחור

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

כדי להריץ את הגרסה הקיימת והגרסה החדשה של API בו-זמנית:

  1. יוצרים קובצי תצורה נפרדים של OpenAPI לכל גרסה שרוצים להציג. בדוגמה הזו השתמשנו בשמות הקבצים openapi-v1.yaml ו-openapi-v2.yaml.

  2. מעתיקים את התוכן של openapi-v1.yaml אל openapi-v2.yaml.

  3. בקטע openapi-v1.yaml מגדירים את האפשרויות הבאות:

    • מגדירים את השדה info.version למספר הגרסה הקיים.
    • משאירים את השדה basePath ללא שינוי.

    לדוגמה:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. בקטע openapi-v2.yaml מגדירים את האפשרויות הבאות:

    • לבצע שינויים שגורמים לאי-תאימות לאחור.
    • מגדירים את השדה info.version למספר הגרסה החדש.
    • מגדירים את השדה basePath כך שיכלול את מספר הגרסה הראשי החדש.
    • מסירים את הקטע x-google-endpoints. הקטע הזה נדרש אם רוצים לציין כתובת IP של DNS או דגל allowCors. כשפורסים שתי גרסאות של ה-API עם שני קובצי תצורה בפורמט YAML, רק לאחד מהם יכול להיות x-google-endpoints, אבל ההגדרה שלו תחול על שתי הגרסאות.

    לדוגמה:

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. משתמשים ב-Google Cloud CLI כדי לפרוס את שני קובצי ההגדרות של ה-API:

    ‫
    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

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

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