תוספים של 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.
ai AI לא ריק הגדרה של תכונות בינה מלאכותית, כולל ניתוב מודלים.

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.

AI אובייקט

אובייקט AI מגדיר יכולות בינה מלאכותית לשירות שלכם, כמו ניתוב מודלים.

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

שדה סוג חובה ברירת מחדל תיאור
models Models לא ריק הגדרת שילובים של מודלים של AI.

Models אובייקט

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

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

שדה סוג חובה ברירת מחדל תיאור
routing Routing לא ריק הגדרת הגדרות ניתוב של מודלים.

Routing אובייקט

אובייקט Routing מגדיר כללי ניתוב ונתבים של מודלים.

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

שדה סוג חובה ברירת מחדל תיאור
routers map[string]Router לא ריק הגדרת נתבי מודלים עם שמות.

Router אובייקט

אובייקט Router מגדיר נתב מודלים עם שם.

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

שדה סוג חובה ברירת מחדל תיאור
defaultModel DefaultModel כן ריק יעד מודל הגיבוי הנדרש שמשמש כשבקשה נכנסת לא תואמת לאף כלל מפורש.
rules [Rule] לא ריק רשימה של כללי ניתוב מודלים מפורשים.

DefaultModel אובייקט

אובייקט DefaultModel מציין את יעד הגיבוי.

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

שדה סוג חובה ברירת מחדל תיאור
backend string כן ריק הפניה לעורף שהוגדר ב-x-google-api-management.backends.
targetModel string כן ריק מציינים את מזהה מודל היעד בפורמט <provider>/<model-id>. במסלולים שתואמים ל-OpenAI, הערך הזה מועבר כמאפיין היוצא model בגוף הבקשה כשמתרחש מעבר לגיבוי.

Rule אובייקט

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

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

שדה סוג חובה ברירת מחדל תיאור
model string כן ריק המחרוזת הנכנסת תואמת למאפיין model במטען הייעודי (payload) בפורמט JSON של הלקוח. במסלולים שתואמים ל-OpenAI, המחרוזת הזו מועברת כמאפיין היוצא model בגוף הבקשה, והיא צריכה להיות מחרוזת <provider>/<model-id> תקינה.
backend string כן ריק הפניה לעורף שהוגדר ב-x-google-api-management.backends.
targetModel string כן ריק מציינים את מזהה מודל היעד בפורמט <provider>/<model-id>. הערך הזה בוחר תרגום של הספק ומוחזר בשדה model בתגובה.

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@"

אם משתמשים בפורמט של מפתח סימטרי, מגדירים את 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 overridden)
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-model-router

אופציונלי.

התוסף x-google-model-router מפנה לנתב מודלים שמוגדר ב-x-google-api-management.ai.models.routing.routers. כשמשתמשים בו, הערך שלו חייב להיות מחרוזת שתואמת לשם של נתב שהוגדר ב-x-google-api-management.ai.models.routing.routers.

ההרחבה הזו נתמכת רק במפרטי OpenAPI 3.x, ואי אפשר להשתמש בה במפרטי OpenAPI 2.0 (Swagger). אפשר להגדיר את התוסף הזה רק ברמת הפעולה האישית לפעולות שמשתמשות בשיטת ה-HTTP‏ POST. אי אפשר לציין גם x-google-model-router וגם x-google-backend באותה פעולה, וגם אי אפשר לשלב בין פעולות של ניתוב לפי מודל לבין פעולות של ניתוב ללא מודל בנתיבים שונים באותו מפרט API.

לדוגמה:

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

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.

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