תוספים של OpenAPI 3.x

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

בדף הזה מתוארים תוספים ספציפיים ל-Google ל-OpenAPI specification 3.x.

למרות שהדוגמאות שמופיעות כאן הן בפורמט YAML, יש תמיכה גם בפורמט JSON.

x-google-api-management

חובה.

התוסף x-google-api-management מגדיר הגדרות ניהול API ברמה העליונה של השירות. מציבים את התוסף הזה בבסיס של מסמך OpenAPI.

בטבלה הבאה מתוארים השדות של x-google-api-management:

שדה סוג חובה ברירת מחדל תיאור
metrics map[string]Metric לא ריק הגדרת מדדים לאכיפת מגבלות המכסה.
quota map[string]Quota לא ריק מציינים את מגבלות המכסה לשירות.
backends map[string]Backend לא ריק הגדרת שירותי קצה עורפי.
apiName string לא ריק משייכים שם לפעולות שמוגדרות במסמך OpenAPI.

Metric אובייקט

אובייקט Metric מגדיר מדד שמשמש לאכיפת מכסות.

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

שדה סוג חובה ברירת מחדל תיאור
displayName string לא ריק השם המוצג של המדד.

Quota אובייקט

אובייקט Quota מגדיר את המגבלות במכסות.

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

שדה סוג חובה ברירת מחדל תיאור
limits map[string]QuotaLimit לא ריק מציינים את המגבלות במכסות.

Quota Limit אובייקט

האובייקט QuotaLimit מגדיר מגבלת מכסה ספציפית.

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

שדה סוג חובה תיאור
metric string כן הפניה למדד שהוגדר במסמך OpenAPI הזה.
values int64 כן מגדירים את הערך המקסימלי שהמדד יכול להגיע אליו לפני שבקשות של לקוחות יידחו.

Backend אובייקט

האובייקט Backend מגדיר שירות קצה עורפי. חובה להגדיר את jwtAudience או את disableAuth.

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

שדה סוג חובה ברירת מחדל תיאור
address string לא ריק מציינים את כתובת ה-URL של ה-Backend.
jwtAudience string לא ריק כברירת מחדל, Endpoints יוצר אסימון מזהה מופע עם קהל JWT שתואם לשדה הכתובת. צריך לציין את jwt_audience באופן ידני רק אם ה-backend של היעד משתמש באימות מבוסס-JWT והקהל הצפוי שונה מהערך שצוין בשדה הכתובת. לשרתי קצה מרוחקים שנפרסו ב-App Engine או עם IAP, צריך לבטל את ברירת המחדל של קהל ה-JWT. ‫App Engine ו-IAP משתמשים במזהה הלקוח שלהם ב-OAuth כקהל הצפוי.
disableAuth bool לא False למנוע משרת ה-proxy של מישור הנתונים לקבל אסימון של מספר מכונה ולצרף אותו לבקשה.
pathTranslation string לא APPEND_PATH_TO_ADDRESS או CONSTANT_ADDRESS מגדירים את אסטרטגיית התרגום של הנתיב כשמבצעים פרוקסי לבקשות לשרת העורפי של היעד. כשמגדירים את x-google-backend ברמה העליונה, ברירת המחדל של pathTranslation היא APPEND_PATH_TO_ADDRESS. כשהערך של x-google-backend מוגדר בפעולה, ערך ברירת המחדל הוא CONSTANT_ADDRESS.
deadline double לא 15.0 מציינים את מספר השניות להמתנה לתגובה מלאה מבקשה. אם לא תענו בזמן, התשובה שלכם לא תתקבל.
protocol string לא http/1.1 הגדרת הפרוטוקול לשליחת בקשה לשרת העורפי. הערכים הנתמכים כוללים http/1.1 ו-h2.

x-google-auth

אופציונלי.

תוסף x-google-auth מגדיר הגדרות אימות באובייקט Security Scheme.

בטבלה הבאה מתוארים השדות של x-google-auth:

שדה סוג חובה ברירת מחדל תיאור
issuer string לא ריק מציינים את המנפיק של פרטי הכניסה. הערכים יכולים להיות שם מארח או כתובת אימייל.
jwksUri string לא ריק מזינים את ה-URI של קבוצת המפתחות הציבוריים של הספק כדי לאמת את החתימה של JSON Web Token.
audiences [string] לא ריק רשימת קהלים שערך השדה aud ב-JWT צריך להיות זהה להם במהלך אימות JWT.
jwtLocations [JwtLocations] לא ריק התאמה אישית של המיקומים של אסימון ה-JWT. כברירת מחדל, JWT מועבר בכותרת Authorization (עם הקידומת Bearer ), בכותרת X-Goog-Iap-Jwt-Assertion או בפרמטר השאילתה access_token.

JwtLocations אובייקט

אובייקט JwtLocations מספק מיקומים מותאמים אישית לאסימון JWT.

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

שדה סוג חובה ברירת מחדל תיאור
header | query string כן לא רלוונטי מציינים את השם של הכותרת שמכילה את ה-JWT, או את השם של פרמטר השאילתה שמכיל את ה-JWT.
valuePrefix string לא ריק לכותרת בלבד. אם המדיניות מוגדרת, הערך שלה חייב להיות זהה לקידומת של ערך הכותרת שמכיל את אסימון ה-JWT.

x-google-quota

אופציונלי.

התוסף x-google-quota מגדיר מגבלות במכסות. אפשר להגדיר את התוסף הזה ברמה העליונה של מסמך OpenAPI או לפעולה ספציפית.

בטבלה הבאה מתוארים השדות של x-google-quota:

שדה סוג חובה תיאור
self map[string]int64 כן אובייקט quota (self) מפנה לכל המדדים שהוגדרו באובייקט. במקרה הזה, ממפים מדד (כמו read-requests) לסכום כדי להגדיל את המדד. הבקשות נדחות כשהערך של המדד מגיע למגבלת המכסה.

x-google-backend

חובה.

התוסף x-google-backend מפנה לקצה עורפי שמוגדר ב-x-google-api-management. צריך להגדיר את התוסף הזה לנקודות קצה. אפשר להגדיר את התוסף הזה ברמה העליונה של מסמך OpenAPI או לפעולה ספציפית.

בטבלה הבאה מתוארים השדות של x-google-backend:

שדה סוג חובה תיאור
self string כן הפניה למזהה של קצה עורפי שמוגדר ב-x-google-api-management.

x-google-endpoint

חובה.

התוסף x-google-endpoint משמש להגדרת המאפיינים של שרת שמוגדר במערך servers של מסמך OpenAPI 3.x. רק רשומה אחת של שרת במסמך OpenAPI יכולה להשתמש בתוסף x-google-endpoint.

התוסף מגדיר גם תכונות אחרות של ה-Backend, כולל:

  • CORS: אפשר להפעיל שיתוף משאבים בין מקורות (CORS) על ידי הגדרת המאפיין allowCors לערך true.
  • נתיב בסיס: נתיב הבסיס שמוגדר בשרת באמצעות x-google-endpoint משמש את ה-API שלכם. לדוגמה, ההגדרה הבאה מגדירה את v1 כנתיב הבסיס:
servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

בטבלה הבאה מתוארים השדות של x-google-endpoint:

שדה סוג חובה ברירת מחדל תיאור
target string לא מציינים את כתובת ה-IP שהמארח מוגדר אליה.
allowCors bool לא false מאפשרים בקשות CORS.

הסבר על המגבלות של תוסף OpenAPI

יש מגבלות ספציפיות על תוספי OpenAPI האלה. מידע נוסף מופיע במאמר בנושא מגבלות של תכונות ב-OpenAPI 3.x.

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

  • אפשר לעיין במפרט OpenAPI.
  • כדאי לעיין במסמכי התיעוד של Endpoints כדי לקבל מידע על הגדרות ספציפיות של Endpoints או ESPv2.