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

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

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

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

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

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

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