מגבלות על תכונות ב-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) בקריאות ארוכות לפונקציות.
• בקשות Batch: מערכי אצווה של 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, בגלל מגבלה ידועה בעיבוד ההגדרות.
• אין התראות על שינויים ברשימת הכלים: השער לא פולט notifications/tools/list_changed. אחרי שפורסים הגדרת API חדשה, הלקוחות צריכים לקרוא שוב ל-tools/list. איך מעדכנים את כלי ה-MCP שחשופים

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

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

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

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

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

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

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

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

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

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

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

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