פריסת ההגדרה של נקודות הקצה

אחרי שמגדירים את Cloud Endpoints במסמך OpenAPI, פורסים אותו כדי ש-Endpoints יקבל את המידע שהוא צריך כדי לנהל את ה-API. כדי לפרוס את ההגדרה של Endpoints, משתמשים בפקודה gcloud endpoints services deploy. הפקודה הזו משתמשת ב-Service Infrastructure, פלטפורמת השירותים הבסיסית של Google, שמשמשת את Endpoints ושירותים אחרים ליצירה ולניהול של ממשקי API ושירותים. בדף הזה מוסבר איך פורסים מסמך OpenAPI ל-Endpoints.

דרישות מוקדמות

כנקודת התחלה, בדף הזה מניחים שיש לכם:

הכנת Google Cloud CLI לפריסה

משתמשים בכלי gcloud של שורת הפקודה כדי לפרוס את ההגדרה. מידע נוסף על הפקודות מופיע ב מדריך העזר ל-gcloud.

כדי להתכונן לפריסה:

  1. מתקינים ומפעילים את ה-CLI של gcloud.
  2. מעדכנים את ה-CLI של gcloud: 
    gcloud components update
  3. מוודאים של-CLI של gcloud יש הרשאה לגשת לנתונים ולשירותים שלכם: 
    gcloud auth login

    תיפתח כרטיסייה חדשה בדפדפן ותתבקשו לבחור חשבון.

  4. מגדירים את פרויקט ברירת המחדל. מחליפים את [YOUR-PROJECT-ID] במזהה הפרויקט ב-GCP. 
    gcloud config set project [YOUR-PROJECT-ID]
  5. אם אתם מתכוונים לפרוס את ה-backend של ה-API ב-Kubernetes או ב-Kubernetes Engine, מריצים את הפקודה הבאה כדי לקבל פרטי כניסה חדשים של משתמש שאפשר להשתמש בהם בפרטי כניסה שמוגדרים כברירת מחדל לאפליקציה. צריך את פרטי הכניסה של המשתמש כדי לתת הרשאה ל-kubectl. 
    gcloud auth application-default login
     נפתחת כרטיסייה חדשה בדפדפן ומוצגת בקשה לבחור חשבון.

אימות התחביר של openapi.json

קובץ מסמך OpenAPI יכול להיות בפורמט YAML או בפורמט JSON. אם הקובץ הוא בפורמט JSON, מומלץ לוודא שהתחביר תקין לפני פריסת הקובץ. כדי לוודא שקובץ ה-openapi.json הוא קובץ JSON בפורמט תקין, אפשר לפתוח אותו בכלי לעריכת טקסט שמאמת JSON, כמו vim, להשתמש בשירות מקוון של JSON linter או להשתמש ב-Python, למשל:

python -m json.tool openapi.json

כדי לשפר את הקריאות, אפשר להדפיס את קובץ ה-JSON בצורה יפה:

python -m json.tool input.json > output.json

מחליפים את input.json בנתיב לקובץ openapi.json. ‫output.json הוא קובץ JSON עם הדפסה מעוצבת.

אימות מסמך OpenAPI

לא כל המבנים של OpenAPI נתמכים כרגע על ידי Cloud Endpoints. לפני הפריסה, אפשר לאמת את מסמך ה-OpenAPI.

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

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

  2. מאשרים את Google Cloud הפרויקט שבו רוצים ליצור את השירות. אם אתם משתמשים בשם דומיין בהתאמה אישית (למשל, myapi.example.com), חשוב לוודא שמזהה הפרויקט שמוחזר מהפקודה הבאה תקין, כדי שהשירות לא ייווצר בפרויקט הלא נכון.

    gcloud config list project

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

    gcloud config set project [YOUR_PROJECT_ID]

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

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only

הפקודה gcloud קוראת ל-Service Management API כדי ליצור שירות מנוהל עם השם שציינתם בשדה host במסמך OpenAPI. כשמציינים את הדגל --validate-only, עדיין נוצר שירות, אבל ההגדרה לא נפרסת. אין דרך לאמת את מסמך ה-OpenAPI בלי ליצור שירות. אפשר למחוק את השירות, אבל כלי ניהול השירותים לא מאפשר ליצור שירות עם אותו שם למשך כ-30 יום.

פריסת מסמך OpenAPI

כשמוכנים לפרוס את ה-API, מריצים את Google Cloud CLI, שמשתמש ב-Service Management כדי להעלות את הגדרת ה-API וליצור (או לעדכן) שירות מנוהל.

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

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

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

    gcloud config list project

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

    gcloud config set project [YOUR_PROJECT_ID]

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

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]

בפעם הראשונה שמריצים את הפקודה הקודמת, 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 .

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

פריסה מחדש

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

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

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