תוספים של OpenAPI 3.x ב-API Gateway

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

בדף הזה מתוארים תוספים ספציפיים ל-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 כן מגדירים את הערך המקסימלי שהמדד יכול להגיע אליו לפני שבקשות של לקוחות יידחו.

Backends אובייקט

חובה.

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

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

שדה סוג חובה ברירת מחדל תיאור
address string כן ריק מציינים את כתובת ה-URL של ה-Backend.
jwtAudience string לא ריק כברירת מחדל, API Gateway יוצר את אסימון מזהה המופע עם קהל 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 מוגדר ברמה העליונה ולא מצוין תג path_translation, ברירת המחדל pathTranslation היא APPEND_PATH_TO_ADDRESS. אם מגדירים את x-google-backend ברמת הפעולה ולא מציינים path_translation, ברירת המחדל היא CONSTANT_ADDRESS.
deadline double לא 15.0 מציינים את מספר השניות להמתנה לתגובה מלאה מבקשה. אם לא תענו בזמן, התשובה שלכם לא תתקבל. הגבלת הזמן המקסימלית היא 600 שניות.
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. ‫API Gateway תומך בשני פורמטים של מפתחות ציבוריים אסימטריים שמוגדרים על ידי התוסף הזה של OpenAPI:

  1. פורמט של קבוצת JWK. לדוגמה: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. ‫X509. לדוגמה: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

אם משתמשים בפורמט של מפתח סימטרי, מגדירים את jwksUri ל-URI של קובץ שמכיל את מחרוזת המפתח בקידוד base64url.
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 משמש בפעולות ספציפיות כדי לציין אילו מדדים שהוגדרו ב-x-google-api-management.metrics מושפעים מבקשות לפעולה הזו.

‫x-google-quota הוא אובייקט שמכיל צמדי מפתח/ערך, כאשר כל מפתח הוא שם של מדד והערך הוא העלות השלמה של כל בקשה לפעולה. לדוגמה:

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overriden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

x-google-backend

חובה.

התוסף x-google-backend מפנה לקצה עורפי שמוגדר ב-x-google-api-management.backends. אם משתמשים בו, הערך שלו צריך להיות מחרוזת שתואמת לשם של קצה עורפי שמוגדר ב-x-google-api-management.backends. צריך להגדיר את התוסף הזה עבור API Gateway. אפשר להגדיר את התוסף הזה ברמה העליונה של מסמך OpenAPI או לפעולה ספציפית כדי לבטל את הגדרת ה-backend ברמה העליונה.

לדוגמה:

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

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:

שדה סוג חובה ברירת מחדל תיאור
allowCors bool לא false מאפשרים בקשות CORS.

x-google-parameter

אופציונלי.

התוסף x-google-parameter מוגדר בפריט parameter. אפשר להשתמש בפרמטר הזה אם הנתיב משתמש בתבניות נתיבים כדי לציין שצריך להשתמש בהתנהגות של התאמה לתווים כלליים כפולים.

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

שדה סוג חובה תיאור
pattern string כן הערך חייב להיות **.

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

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

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