שינוי Cloud Endpoints לשימוש ב-OpenAPI 3.x

בדף הזה מוסבר איך להשתמש במפרט OpenAPI 3.x כשמגדירים Endpoints.

לפני שמתחילים

  • מוודאים שיש לכם מופע Endpoints קיים שהוגדר עם מפרט OpenAPI 2.0.
  • מתקינים את gcloud CLI. מידע נוסף זמין במאמר התקנת Google Cloud CLI.

שינוי ההגדרה של Endpoints כדי להשתמש ב-OpenAPI 3.x

כדי לשנות הגדרה קיימת של נקודות קצה ב-OpenAPI 2.0 כך שתשתמש ב-OpenAPI 3.x, צריך לבצע את השלבים הבאים.

צפייה בהיסטוריית הפריסה

כדי לראות את היסטוריית הפריסה:

  1. במסוף Google Cloud , נכנסים לדף Endpoints > Services.

    לדף Endpoints Services

  2. ברשימת הפרויקטים, בוחרים את הפרויקט הרצוי.

  3. אם יש לכם יותר מ-API אחד, בוחרים API מהרשימה.

  4. כדי לראות רשימה של פריסות של הגדרות שירות, לוחצים על הכרטיסייה Deployment history. הרשימה כוללת:

    • מזהה ההגדרה.
    • התאריך שבו נפרסה הגדרת השירות.
    • מי פרס את הגדרת השירות.

צפייה בהגדרת השירות

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

המרת מסמך OpenAPI ל-OpenAPI 3.x

המרת מסמך OpenAPI 2.0 ל-OpenAPI 3.x. אפשר להשתמש בכלי שתומך בהמרה הזו ל-OpenAPI 3.x. לדוגמה, Swagger Editor מספק כלי להמרה.

אחרי ההמרה הראשונית ל-OpenAPI 3.x, צריך להחיל באופן ידני שינויים נוספים במסמך כדי להתאים אותו ל-OpenAPI 3.x ולוודא שהוא תואם לתוספים ולתכונות של Endpoints.

בטבלה הבאה מתוארים השינויים הנדרשים:

תכונה OpenAPI 2.0 ‫OpenAPI 3.x תיאור השינוי
מפתח API securityDefinitions securitySchemes מפתחות API משתמשים בתמיכה במפתחות API של OpenAPI שזמינה מחוץ לקופסה. בדרך כלל, כלי המרות מטפלים בזה באופן אוטומטי. אין צורך לבצע שינויים ידניים.
אימות JWT ‫x-google-audiences וכו'. x-google-auth בתוספים של OpenAPI 2.0, מגדירים את OAuth באמצעות תוספים נפרדים במופע securityDefinition. כלי ההמרה ממירים את מופע תוכנית האבטחה ל-#/components/securitySchemes ומשאירים את התוספים. צריך לשנות את התוספים האלה באופן ידני כך שיהיו צאצאים של x-google-auth ולהסיר את הקידומת x-google-. הערכים נשארים ללא שינוי.
מכסה x-google-management, x-google-quota x-google-api-management, x-google-quota בתוספים של OpenAPI 2.0, מגדירים מדדים ומכסות באמצעות x-google-management ומצרפים אותם באמצעות x-google-quota. כלי ההמרה משאירים את התוספים האלה במקומם. העברה ידנית של מדדים והגדרות מכסה מ-x-google-management אל x-google-api-management. משנים את ההגדרות כך שישתמשו במפתחות YAML ומסירים את valueType, metricKind ו-unit. הסרת metricCosts מהמופעים של x-google-quota.
קצה עורפי x-google-backend x-google-api-management, x-google-backend בתוספים של OpenAPI 2.0, מגדירים את ה-backends ב-x-google-backend, וההגדרה חלה במקום שבו היא מוגדרת. בתוספים של OpenAPI 3.x, מגדירים את ה-backend באמצעות x-google-api-management ואז מחילים אותו באמצעות x-google-backend. כלי ההמרות לא מסירים את התוסף הזה. מעבירים את ההגדרה באופן ידני אל x-google-api-management. משנים את המופעים של x-google-backend כך שיפנו להגדרה הזו.
נקודות קצה x-google-endpoints x-google-endpoint, servers בתוספים של OpenAPI 2.0, מגדירים את נקודות הקצה ב-x-google-endpoints. בתוספים של OpenAPI 3.x, משתמשים ב-x-google-endpoint, אבל זהו תוסף של servers ולא של השורש. כלי ההמרה לא מסירים את התוסף הזה. מעבירים את זה ידנית אל servers ומסירים את השדה name. לדוגמה: 
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
שמות של ממשקי API x-google-api-name x-google-api-management בתוספים של OpenAPI 2.0, מגדירים שמות של API ב-x-google-api-name. בתוספים של OpenAPI 3.x, משתמשים בשדה apiName ב-x-google-api-management. העברה ידנית של ההגדרה הזו אל x-google-api-management.
מתן הרשאה לכל התנועה x-google-allow לא נתמך מסירים את זה ממסמך ה-OpenAPI. ‫Endpoints לא תומך בזה ב-OpenAPI 3.x.

פריסה מחדש של הגדרת השירות

בכל פעם שמשנים משהו במסמך OpenAPI, חשוב לפרוס אותו מחדש כדי שמודול Endpoints יקבל את הגרסה העדכנית ביותר של הגדרות השירות של ה-API. אם כבר פרסתם את ה-ESP עם האפשרות rollout שהוגדרה ל-managed, לא צריך לפרוס מחדש או להפעיל מחדש את ה-ESP. האפשרות הזו מגדירה את ESP כך שישתמש בהגדרות השירות העדכניות ביותר שפרסמתם. אם תבחרו באפשרות הזו, עד 5 דקות אחרי שתפרסו הגדרת שירות חדשה, ESP יזהה את השינוי ויתחיל להשתמש בה באופן אוטומטי. אנחנו ממליצים לציין את האפשרות הזו במקום מזהה תצורה ספציפי לשימוש ב-ESP.

כדי לפרוס את מסמך ה-OpenAPI:

  1. מעבירים את הספרייה למיקום שמכיל את מסמך OpenAPI.

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

    gcloud config list project

    אם אתם צריכים לשנות את פרויקט ברירת המחדל, מריצים את הפקודה הבאה ומחליפים את YOUR_PROJECT_ID ב Google Cloud מזהה הפרויקט שבו אתם רוצים ליצור את השירות:

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. מריצים את הפקודה הבאה ומחליפים את YOUR_OPENAPI_DOCUMENT בשם של מסמך OpenAPI שמתאר את ה-API:

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

בפעם הראשונה שמריצים את הפקודה הקודמת, Service Management יוצר שירות Endpoints חדש בפרויקט שמוגדר כברירת מחדל, עם שם שתואם לטקסט שצוין בשדה host במסמך OpenAPI, ומעלה את הגדרת השירות.

במהלך היצירה וההגדרה של השירות, Service Management מציג מידע במסוף. בסיום מוצלח, תופיע שורה כמו זו שבהמשך, שבה מוצג מזהה הגדרת השירות ושם השירות:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

בדוגמה הקודמת, 2017-02-13r0 הוא מזהה הגדרות השירות ו-echo-api.endpoints.example-project-12345.cloud.goog הוא שם השירות.

אחרי פריסה מוצלחת, אפשר לראות את ה-API בדף Endpoints > Services במסוף Google Cloud .

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

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