תוספים של 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	לא	ריק	הגדרה של תכונות בינה מלאכותית, כולל ניתוב מודלים.
mcp	MCP או bool	לא	ריק	הפעלה או הגדרה של תכונות Model Context Protocol‏ (MCP).

זהירות: לפני שיוצרים הגדרת API חדשה, חשוב לוודא שמדדי המכסה והמגבלות נשארים עקביים בכל הגדרות ה-API הפעילות. ‫API Gateway מחיל את metrics ו-quota על ה-API כולו ולא על הגדרת API ספציפית, כך שכל מדד או מגבלה שמוגדרים בהגדרת API חדשה מחליפים את ההגדרה של ה-API כולו. אם משנים את השם של מדד או מסירים אותו, השיטות שמוגבלות על ידי מכסה של כל שער שעדיין משרת תצורת API קודמת מחזירות שגיאת HTTP 500. מידע נוסף מופיע במאמר בנושא מכסות חלות על ה-API כולו.

אובייקט Metric

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

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

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

אובייקט Quota

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

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

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

אובייקט QuotaLimit

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

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

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

אובייקט Backends

חובה.

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

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

שדה	סוג	חובה	ברירת מחדל	תיאור
address	string	כן	ריק	מציינים את כתובת ה-URL של הקצה העורפי.
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 מוגדר כ-on ברמת הפעולה ולא מצוין path_translation, ברירת המחדל היא CONSTANT_ADDRESS.
deadline	double	לא	15.0	מציינים את מספר השניות להמתנה לתגובה מלאה מבקשה. התשובות שיישלחו אחרי המועד הזה לא יתקבלו. בנקודת קצה של SSE או של העברה בחלקים, מועד היעד עדיין מגביל את משך הזמן של כל הזרם. בנקודת קצה של gRPC או של WebSocket, הוא מגביל את הפער בין ההודעות. במאמר הגדרת מועד אחרון לשידור מפורטים ערכי הזמן הקצובים לתפוגה שחלים על כל סוג של בקשה. אפשר להגדיר את הדדליין עד 3,600 שניות. שער שאינו סטרימינג אוכף מקסימום נמוך יותר של 600 שניות, ודוחה מועד סיום גבוה יותר ביצירה או בעדכון של השער ולא ביצירה של הגדרת ה-API.
protocol	string	לא	http/1.1	הגדרת הפרוטוקול לשליחת בקשה לקצה העורפי. הערכים הנתמכים כוללים http/1.1 ו-h2. דרישות הפרוטוקול תלויות בסוג הסטרימינג: - gRPC: צריך להגדיר את הפרוטוקול ל-h2. - WebSockets: צריך להשתמש ב-http/1.1. - Server-Sent Events (SSE)‎ ושליחת תגובה מצטברת: אפשר להשתמש ב-http/1.1 או ב-h2. מומלץ להשתמש ב-h2 כדי לשפר את הביצועים.

אובייקט AI

האובייקט 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 בתגובה.

אובייקט MCP

אובייקט MCP מגדיר את התכונות של Model Context Protocol‏ (MCP) בשירות. אפשר להגדיר את mcp כערך בוליאני או כאובייקט. הערך true מפעיל את MCP באופן גלובלי לכל הפעולות שעומדות בדרישות עם הגדרות ברירת מחדל.

הערה: אי אפשר להשתמש ב-MCP ובניתוב מודלים יחד באותה הגדרת API. אם הערך של x-google-api-management.mcp מוגדר, אי אפשר להגדיר את x-google-model-router באף פעולה.

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

שדה	סוג	חובה	ברירת מחדל	תיאור
tools-list	ToolsList	לא	ריק	מגדירים את ההגדרות לשיטת ה-MCP‏ tools/list.

אובייקט ToolsList

האובייקט ToolsList מגדיר את ההגדרות של שיטת ה-MCP‏ tools/list.

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

שדה	סוג	חובה	ברירת מחדל	תיאור
security	map	לא	ריק	הפעלת אימות ב-tools/list. מומלץ מאוד להגדיר את האפשרות הזו כשיטת אבטחה מומלצת. צריך לציין בדיוק סכימת אבטחה אחת של JWT שמוגדרת בקטע components.securitySchemes. ב-Public Preview אין תמיכה באימות באמצעות מפתח API.

x-google-auth

אופציונלי.

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

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

שדה	סוג	חובה	ברירת מחדל	תיאור
issuer	string	לא	ריק	מציינים את המנפיק של פרטי הכניסה. הערכים יכולים להיות שם מארח או כתובת אימייל.
jwksUri	string	לא	ריק	מזינים את ה-URI של קבוצת המפתחות הציבוריים של הספק כדי לאמת את החתימה של אסימון האינטרנט מסוג JSON. ‫API Gateway תומך בשני פורמטים של מפתחות ציבוריים אסימטריים שמוגדרים על ידי התוסף הזה של OpenAPI: פורמט של קבוצת JWK. לדוגמה: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json" ‫X509. לדוגמה: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/[e-mail]" אם אתם משתמשים בפורמט של מפתח סימטרי, צריך להגדיר את jwksUri ל-URI של קובץ שמכיל את מחרוזת המפתח בקידוד base64url.
audiences	[string]	לא	ריק	רשימה של קהלים ששדה ה-JWT‏ aud צריך להיות זהה להם במהלך אימות 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. בנוסף, אי אפשר להשתמש בניתוב מודלים בשילוב עם Model Context Protocol‏ (MCP). אם מפעילים את x-google-api-management.mcp, התוסף הזה לא זמין.

לדוגמה:

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-mcp-tool

אופציונלי.

התוסף x-google-mcp-tool משמש בפעולות ספציפיות כדי לחשוף אותן ככלי MCP, ויש לו אפשרות לדרוס את השם והתיאור של הכלי שנוצרו.

התוסף הזה נתמך רק במפרטים של OpenAPI 3.x, ואי אפשר להשתמש בו במפרטים של OpenAPI 2.0 ‏ (Swagger). אפשר להגדיר את התוסף הזה רק ברמת הפעולה הבודדת.

המאפיין מקבל ערך בוליאני או אובייקט.

• טופס בוליאני: מגדירים את הערך true כדי להפעיל את הפעולה הזו. מגדירים את הערך false כדי לבטל את ההסכמה, וכך לבטל את ההפעלה הגלובלית.
• טופס אובייקט: אפשר להביע הסכמה ולשנות את הגדרות הכלי שנוצרו.

בטבלה הבאה מתוארים השדות של x-google-mcp-tool כשמשתמשים בו כאובייקט:

שדה	סוג	חובה	ברירת מחדל	תיאור
name	string	לא	‫operationId של הפעולה	שם כלי ה-MCP. חייב להיות זהה לערך של [A-Za-z0-9_.-]{1,128} וייחודי במפרט.
description	string	לא	תיאור הפעולה, או סיכום אם אין תיאור	תיאור כלי ה-MCP. זהו האות העיקרי שמשמש מודל LLM לבחירת כלי.

לדוגמה:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

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.

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

• אפשר לעיין במפרט OpenAPI.
• איך משנים שער כדי להשתמש ב-OpenAPI 3.0