מגבלות על תכונות של OpenAPI 3.x

במסמך הזה מפורטות מגבלות התכונות של שימוש ב-OpenAPI 3.x עם API Gateway.

מידע נוסף על גרסאות נתמכות של מפרט OpenAPI זמין במאמר סקירה כללית על OpenAPI.

מגבלות חדשות ב-OpenAPI 3.x

בקטע הזה מתוארות מגבלות של תכונות חדשות ב-OpenAPI 3.x.

שרתים

‫OpenAPI 3.x תומך במספר אובייקטים של server כדי להגדיר מארחים ונתיבי בסיס. עם זאת, API Gateway מסתמך על אובייקט שרת יחיד, שמזוהה על ידי התוסף x-google-endpoint, כדי להגדיר את השירות.

אפשר להגדיר כמה שרתים, אבל API Gateway מתייחס רק לשרת שמכיל את התוסף x-google-endpoint, ומאפשר רק שרת אחד כזה. ב-API Gateway, לא נדרשת כתובת אתר של שרת, כך שאפשר לא להגדיר שרתים או להגדיר שרת אחד עם התוסף x-google-endpoint.

לדוגמה, ההגדרות הבאות הן תקינות ל-API Gateway:

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

ההגדרה הבאה לא תקינה כי היא מכילה כמה תוספים של x-google-endpoint:

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

ההגדרה הבאה תקפה ל-API Gateway, אבל API Gateway מתעלם מאובייקט השרת:

servers:
  - url: https://example.com

שרתים בכמה קבצים

אם מעלים כמה קובצי OpenAPI ואחד מהם מכיל שרת עם התוסף x-google-endpoint, אז כל הקבצים צריכים להכיל גם שרת מוגדר עם אותו תוסף x-google-endpoint ואותו מארח בכתובת ה-URL של השרת. נתיב הבסיס עשוי להיות שונה בין קבצים.

כתובת URL יחסית

ב-API Gateway, כתובות URL יחסיות באובייקט servers נחשבות לנתיב בסיסי בפני עצמו, כי לא נדרש שם מארח במפרט. ההתנהגות הזו שונה מההתנהגות הרגילה של OpenAPI, שבה כתובות URL יחסיות נפתרות מול השרת שמארח את הגדרת OpenAPI. לדוגמה, ב-API Gateway,‏ url: /v1 נחשב כנתיב בסיס.

נתיבי הבסיס חייבים להתחיל ב-'/'. API Gateway דוחה כתובות URL שאין להן סכימה או שמתחילות ב-'/' כדי לציין נתיב בסיס.

תוספים שלא נתמכים

‫API Gateway לא תומך בתוסף x-google-allow ל-OpenAPI 3.x.

מגבלות גודל הקובץ

ב-API Gateway יש מגבלת גודל כוללת של 10MB ומגבלת מספר קבצים של 50 לקבצים מסוג OpenAPI 3.x שמועלים.

מגבלות של MCP

במהלך תקופת ה-Public Preview, חלות ההגבלות הבאות על התמיכה ב-Model Context Protocol‏ (MCP):

• מגבלת מספר הכלים: לקוחות מוגבלים ל-1,000 כלים לכל היותר של MCP לכל שער.
• שיטות HTTP: אפשר לחשוף רק פעולות GET,‏ POST,‏ PUT,‏ PATCH ו-DELETE ככלים של MCP. אין תמיכה ב-HEAD, ‏OPTIONS ו-TRACE.
• סטרימינג: אין תמיכה בסטרימינג של אירועים שנשלחים מהשרת (SSE) של קריאות ארוכות לכלים.
• בקשות באצווה: מערכים של אצווה ב-JSON-RPC נדחים.
• מטענים ייעודיים (payloads) מרובי-אופנים: התשובות של כלי מוגבלות לטקסט בקידוד UTF-8. אין תמיכה בתשובות בינאריות.
• חוסר מצב: ההטמעה היא חסרת מצב. לא נעשה שימוש במזהי סשנים (כמו MCP-Session-Id) ולא מתבצעת תחזוקה שלהם.
• שיטות MCP לא אפשריות: שיטות מיוחדות כמו resources/*,‏ prompts/*,‏ sampling/*,‏ completion/*,‏ ping ו-logging/* לא אפשריות ומחזירות קוד שגיאה של JSON-RPC‏ -32601.
• הגבלות על אימות: השיטה tools/list תומכת רק באימות JWT. השיטה הזו לא תומכת באימות באמצעות מפתח API.
• אין הערות בכלי: רמזים כמו destructiveHint או readOnlyHint לא מופיעים בהצהרות על כלים.
• CORS Preflight: הטיפול האוטומטי ב-CORS Preflight (בקשות OPTIONS) בנתיב /mcp לא מנוהל על ידי שער.
• הדרה הדדית של ניתוב מודלים: אי אפשר להשתמש גם ב-MCP וגם בניתוח מודלים באותה הגדרת API.
• תגובות MCP לא אפשריות: פעולות שמחזירות גופים ריקים בתגובה, כמו תגובות HTTP 204, לא אפשריות.
• גילוי סכימה: יכול להיות שסכימות מורכבות של אובייקטים מוטמעים שנגזרות ממפרט OpenAPI לא יוצגו באופן מלא או נכון בתגובת הגילוי tools/list בגלל מגבלה ידועה בעיבוד ההגדרה.

מגבלות קיימות

בקטע הזה מתוארות מגבלות שקיימות מ-OpenAPI 2.0 ועדיין חלות על OpenAPI 3.x.

היקפי הרשאה שהמערכת התעלמה מהם

למרות ש-API Gateway מקבל מסמכי OpenAPI עם היקפי הרשאות שמוגדרים באובייקט של תוכנית אבטחה, הוא לא בודק את היקפי ההרשאות האלה ולא אוכף אותם.

כמה דרישות אבטחה

• דרישות לגבי מפתח API: ‏ API Gateway לא תומך בדרישות אבטחה חלופיות (לוגיות OR) אם אחת מהסכימות היא מפתח API. עם זאת, API Gateway תומך בחיבורים (logical AND), כך שאפשר לדרוש גם מפתח API וגם אסימון OAuth2.
• דרישות OAuth2: API Gateway תומך בדרישות אבטחה חלופיות (לוגיות OR) עבור תוכניות אבטחה שונות של OAuth2. ‫API Gateway לא תומך בחיבורים (logical AND) אלא אם דרישת האבטחה הנוספת היא מפתח API.
• אבטחה אופציונלית: אפשר להשתמש בדרישת אבטחה ריקה (- {}) כדי להפוך את האבטחה לאופציונלית עבור מפתח API, אבל API Gateway לא תומך באפשרות הזו עבור OAuth.

אימות הגדרת האבטחה

‫API Gateway ידחה מפרט OpenAPI 3.x שנעשה בו שימוש בדרישת אבטחה ללא הגדרה תואמת בקטע securityDefinitions.

תבניות של נתיבי כתובות URL

API Gateway תומך רק בפרמטרים של תבנית נתיב כתובת ה-URL שמייצגים פלחים שלמים של נתיב, לדוגמה, /items/{itemId}. ‫API Gateway לא תומך בפרמטרים שמתאימים לפלחים חלקיים ודוחה אותם, לדוגמה, /items/prefix_{id}_suffix.

פרמטרים, סכימות, גופי בקשות וסוגים

‫API Gateway מקבל מסמכי OpenAPI עם הגדרות שונות של פרמטרים וסוגים (לדוגמה, פרמטרים של required ופורמטים של מערכים), אבל הוא לא אוכף אותם. ‫API Gateway מעביר בקשות נכנסות ל-API שלכם ללא קשר להגדרות האלה.

‫API Gateway תומך רק בסוגים פרימיטיביים בפרמטרים של בקשות.

הפניות לסוגים חיצוניים

‫API Gateway לא תומך בהפניות לסוגים מחוץ למסמך OpenAPI שסופק. לדוגמה, API Gateway לא מאפשר $ref שמפנה לכתובת URL חיצונית ודוחה אותה.

יציאה מותאמת אישית בכתובת המארח

‫API Gateway לא מאפשר יציאות מותאמות אישית בשדה servers.url של מסמך OpenAPI.

מגבלות על כינויי YAML

מסמך OpenAPI שנשלח אל API Gateway יכול להכיל עד 200 צמתי כינוי של YAML.