הגדרת Cloud Endpoints

‫Cloud Endpoints תומך בממשקי API שמתוארים באמצעות גרסה 2.0 של מפרט OpenAPI. אתם מתארים את המשטח של ה-API ומגדירים תכונות של Endpoints כמו כללי אימות או מכסות במסמך OpenAPI.

‫Endpoints משתמש באופן מיוחד בשדות הנדרשים הבאים במסמך OpenAPI:

  • host
  • info.title
  • info.version
  • operationId

בדף הזה מוסבר איך Endpoints משתמש בשדות הקודמים. בעזרת המידע הזה, תוכלו לסיים את ההכנה של מסמך OpenAPI לפריסה.

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

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

host

‫Cloud Endpoints משתמש בשם שמוגדר בשדה host במסמך OpenAPI כשם השירות.

השם של שירות ה-API חייב להיות ייחודי ב- Google Cloud. מכיוון ש-Endpoints משתמש בשמות שתואמים ל-DNS כדי לזהות שירותים, מומלץ להשתמש בשם הדומיין או בשם תת-הדומיין של ה-API כשם השירות. בגישה הזו, שם השירות שמופיע בדף Endpoints Services זהה לשם שמשמש בבקשות ל-API. יש ב-Endpoints את הדרישות הבאות לשם השירות:

  • The maximum length of the domain name is 253 characters.
  • The domain name must start with a lowercase letter.
  • Each section in the domain name, which is delimited by dots, has the following requirements:
    • Must start with a lowercase letter.
    • Must not end with a dash.
    • The remaining characters can be lowercase letters, numbers, or dashes.
    • The maximum length is 63 characters.

אתם יכולים לרשום דומיין מותאם אישית משלכם (למשל example.com), או להשתמש בדומיין שמנוהל על ידי Google.

שימוש בדומיין שמנוהל על ידי Google

‫Google היא הבעלים של הדומיינים cloud.goog ו-appspot.com והיא מנהלת אותם. אם רוצים להשתמש בדומיין שמנוהל על ידי Google, צריך להשתמש במזהה הפרויקטGoogle Cloud כחלק משם השירות. מכיוון שלפרויקטיםGoogle Cloud יש מזהה פרויקט ייחודי גלובלי, הדרישה הזו מבטיחה שיהיה לכם שם שירות ייחודי.

שם הדומיין שבו אתם משתמשים תלוי בשרת העורפי שמארח את ה-API:

  • בממשקי API שמארחים בסביבה הגמישה של App Engine, צריך להשתמש בדומיין appspot.com, ושם השירות צריך להיות בפורמט הבא, כאשר YOUR_PROJECT_ID הוא Google Cloud מזהה הפרויקט:

    YOUR_PROJECT_ID.appspot.com

    כשפורסים את ה-API ב-App Engine, נוצרת אוטומטית רשומת DNS עם שם בפורמט YOUR_PROJECT_ID.appspot.com.

  • ב-APIs שמארחים ב-Compute Engine, ב-Google Kubernetes Engine או ב-Kubernetes, צריך להשתמש בדומיין cloud.goog, ושם השירות צריך להיות בפורמט הבא, כאשר YOUR_API_NAME הוא שם ה-API:

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog

    כדי להשתמש בדומיין הזה כשם הדומיין של ה-API, כדאי לקרוא את המאמר בנושא הגדרת DNS בדומיין cloud.goog.

שימוש בדומיין מותאם אישית

אם אתם לא רוצים להשתמש בדומיין שמנוהל על ידי Google, אתם יכולים להשתמש בדומיין מותאם אישית (לדוגמה, myapi.mycompany.com) שיש לכם הרשאה להשתמש בו. לפני שמפעילים את הגדרת ה-API, צריך לפעול לפי השלבים במאמר אימות הבעלות על הדומיין.

info.title

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

info.version

בדף Endpoints > Services במסוף Google Cloud מוצג מספר הגרסה של ה-API. לפני שפורסים את הגדרות ה-API בפעם הראשונה:

  • מגדירים את מספר הגרסה בשדה info.version לגרסת ה-API הרלוונטית,לדוגמה, 1.0.

  • מגדירים את השדה basePath למספר הגרסה הראשית, לדוגמה, /v1.

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

operationId

למרות ש-operationId הוא שדה אופציונלי במפרט OpenAPI,‏ Endpoints דורש את השדה הזה כי הוא משמש לזיהוי פנימי של הפעולה. המחרוזת שבה משתמשים ב-operationId חייבת להיות ייחודית ב-API. הנחיות לגבי מתן שמות זמינות בתיאור של operationId במפרט OpenAPI.

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