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

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

בדף הזה מתוארות ההרחבות הספציפיות של Google למפרט OpenAPI בגרסה 3.x.

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

x-google-api-management

חובה.

התוסף x-google-api-management מגדיר את הגדרות ניהול ממשקי ה-API ברמה העליונה של השירות. מציבים את התוסף הזה ברמה הבסיסית (root) של מסמך 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. מידע נוסף זמין במאמר Quotas apply to the whole 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 רק אם בקצה העורפי של היעד נעשה שימוש באימות מבוסס-JWT, והקהל הצפוי שונה מהערך שצוין בשדה הכתובת. ב-backends מרוחקים שנפרסו ב-App Engine או באמצעות IAP, צריך לשנות את הקהל של ה-JWT. ב-App Engine וב-IAP, מזהה הלקוח ב-OAuth משמש כקהל הצפוי.
disableAuth	bool	לא	False	למנוע מהשרת proxy של מישור הנתונים לקבל טוקן של מזהה מכונה ולצרף אותו לבקשה.
pathTranslation	string	לא	APPEND_PATH_TO_ADDRESS או CONSTANT_ADDRESS	הגדרת שיטת התרגום של הנתיב כששולחים בקשות דרך שרת proxy לקצה העורפי של היעד. כשמגדירים את x-google-backend ברמה העליונה ולא מציינים path_translation, ערך ברירת המחדל של pathTranslation הוא APPEND_PATH_TO_ADDRESS. כשמגדירים את x-google-backend ברמת הפעולה ולא מציינים path_translation, ברירת המחדל היא CONSTANT_ADDRESS.
deadline	double	לא	15.0	מציינים את מספר השניות שצריך להמתין לתגובה מלאה לבקשה. תגובות שחורגות מהמועד האחרון הזה לא יתקבלו. בנקודת קצה (endpoint) של SSE או של העברה מקוטעת, המועד האחרון עדיין מגביל את משך הזמן של כל הסטרימינג. בנקודת קצה של gRPC או של WebSocket, הוא מגביל את הפער בין ההודעות. בקטע הגדרת המועד האחרון לסטרימינג מפורטים זמני הקצובות לתפוגה שחלים על כל סוג של בקשה. כדי להשתמש בברירת המחדל, משמיטים את השדה או מגדירים אותו כ-0. ערך שלילי נדחה. אפשר להגדיר את המועד האחרון עד 3,600 שניות. שער ללא סטרימינג אוכף מגבלה נמוכה יותר של 600 שניות, ודוחה מועד אחרון גבוה יותר ביצירה או בעדכון של השער, ולא ביצירה של הגדרת ה-API.
protocol	string	לא	http/1.1	מגדירים את הפרוטוקול לשליחת בקשה לקצה העורפי. הערכים הנתמכים כוללים את http/1.1 ו-h2. דרישות הפרוטוקול תלויות בסוג הסטרימינג: - gRPC: צריך להגדיר את הפרוטוקול ל-h2. - WebSockets: צריך להשתמש ב-http/1.1. - אירועים שנשלחים מהשרת (SSE) והעברת תגובות מצטברות: אפשר להשתמש ב-http/1.1 או ב-h2. כדי לשפר את הביצועים, מומלץ להשתמש ב-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 היוצא בגוף הבקשה כשמתרחש החלפת ה-API.

אובייקט 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 קובע את ההגדרות של ה-method‏ tools/list ב-MCP.

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

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

x-google-auth

אופציונלי.

התוסף x-google-auth מגדיר את הגדרות האימות בתוך אובייקט של סכימת אבטחה.

בטבלה הבאה מתוארים השדות של 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). אפשר להגדיר את התוסף הזה רק ברמת הפעולה הנפרדת, לפעולות שמשתמשות ב-method‏ POST של HTTP. אי אפשר לציין גם את 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). אפשר להגדיר את התוסף הזה רק ברמת הפעולה הספציפית.

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

• Boolean form: מגדירים את הערך 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.

התוסף גם מגדיר תכונות אחרות של קצה עורפי, כולל:

• ‫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.