Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Einschränkungen der OpenAPI 3.x-Funktionen

In diesem Dokument werden die Funktionseinschränkungen für die Verwendung von OpenAPI 3.x mit API Gateway beschrieben.

Weitere Informationen zu unterstützten OpenAPI-Spezifikationsversionen finden Sie unter OpenAPI – Übersicht.

Neue OpenAPI 3.x-Einschränkungen

In diesem Abschnitt werden die Einschränkungen für neue Funktionen in OpenAPI 3.x beschrieben.

Server

OpenAPI 3.x unterstützt mehrere server-Objekte, um Hosts und Basispfade zu definieren. API Gateway verwendet jedoch ein einzelnes Serverobjekt, das durch die Erweiterung x-google-endpoint identifiziert wird, um den Dienst zu konfigurieren.

Sie können zwar mehrere Server definieren, API Gateway berücksichtigt jedoch nur den Server, der die Erweiterung x-google-endpoint enthält, und lässt nur einen solchen Server zu. Für API Gateway ist keine Server-URL erforderlich. Sie können also entweder keine Server oder einen Server mit der Erweiterung x-google-endpoint definieren.

Die folgenden Definitionen sind beispielsweise für API Gateway gültig:

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

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

Die folgende Definition ist ungültig, da sie mehrere x-google-endpoint-Erweiterungen enthält:

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

Die folgende Definition ist für API Gateway gültig, aber API Gateway ignoriert das Serverobjekt:

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

Server in mehreren Dateien

Wenn Sie mehrere OpenAPI-Dateien hochladen und eine Datei einen Server mit der Erweiterung x-google-endpoint enthält, müssen alle Dateien auch einen Server mit einer identischen x-google-endpoint-Erweiterung und einem identischen Host in der Server-URL haben. Der Basispfad kann sich von Datei zu Datei unterscheiden.

Relative URL

Bei API Gateway werden relative URLs im servers-Objekt als eigener Basispfad behandelt, da in der Spezifikation kein Hostname erforderlich ist. Dies unterscheidet sich vom standardmäßigen OpenAPI-Verhalten, bei dem relative URLs anhand des Servers aufgelöst werden, auf dem die OpenAPI-Definition gehostet wird. API Gateway behandelt beispielsweise url: /v1 als Basispfad.

Basispfade müssen mit „/“ beginnen. API Gateway lehnt URLs ab, die kein Schema haben oder nicht mit „/“ beginnen, um einen Basispfad anzugeben.

Nicht unterstützte Erweiterungen

API Gateway unterstützt die Erweiterung x-google-allow für OpenAPI 3.x nicht.

Maximale Dateigrößen

API Gateway erzwingt eine Gesamtgrößenbeschränkung von 10 MB und eine Dateianzahlbeschränkung von 50 für hochgeladene OpenAPI 3.x-Dateien.

MCP-Einschränkungen

Während der öffentlichen Vorschau gelten für die Unterstützung des Model Context Protocol (MCP) die folgenden Einschränkungen:

Begrenzung der Toolanzahl: Kunden können maximal 1.000 MCP-Tools pro Gateway verwenden.
HTTP-Methoden: Nur die Vorgänge GET, POST, PUT, PATCH und DELETE können als MCP-Tools bereitgestellt werden. HEAD, OPTIONS und TRACE werden nicht unterstützt.
Streaming: Das Streaming von Server-Sent Events (SSE) für Toolaufrufe mit langer Ausführungszeit wird nicht unterstützt.
Batchanfragen: JSON-RPC-Batcharrays werden abgelehnt.
Multimodale Nutzlasten: Toolantworten sind auf UTF-8-Text beschränkt. Binäre Antworten werden nicht unterstützt.
Zustandslosigkeit: Die Implementierung ist zustandslos. Sitzungskennungen (wie MCP-Session-Id) werden nicht verwendet oder verwaltet.
Nicht unterstützte MCP-Methoden: Spezielle Methoden wie resources/*, prompts/*, sampling/*, completion/*, ping und logging/* werden nicht unterstützt und geben den JSON-RPC-Fehlercode -32601 zurück.
Keine Tool-Annotationen: Hinweise wie destructiveHint oder readOnlyHint werden in Tool-Deklarationen nicht ausgegeben.
CORS-Preflight: Die automatisierte CORS-Preflight-Verarbeitung (OPTIONS-Anfragen) im Pfad /mcp wird nicht vom Gateway verwaltet.
Gegenseitiger Ausschluss von Modell-Routing: Sie können MCP und Modell-Routing nicht in derselben API-Konfiguration verwenden.
Nicht unterstützte MCP-Antworten: Vorgänge, die leere Textkörper in der Antwort zurückgeben, z. B. HTTP-204-Antworten, werden nicht unterstützt.
Schemaerkennung: Komplexe verschachtelte Objektschemas, die aus Ihrer OpenAPI-Spezifikation abgeleitet wurden, werden aufgrund einer bekannten Einschränkung bei der Konfigurationsverarbeitung möglicherweise nicht vollständig oder korrekt in der tools/list-Erkennungsantwort gerendert.
Keine Benachrichtigungen über Änderungen der Toolliste: Das Gateway gibt keine notifications/tools/list_changed aus. Nachdem Sie eine neue API-Konfiguration bereitgestellt haben, müssen Clients tools/list noch einmal aufrufen. Weitere Informationen finden Sie unter Verfügbare MCP-Tools aktualisieren.

Bestehende Einschränkungen

In diesem Abschnitt werden Einschränkungen beschrieben, die von OpenAPI 2.0 übernommen wurden und auch für OpenAPI 3.x gelten.

Ignorierte Bereiche

API Gateway akzeptiert zwar OpenAPI-Dokumente mit Bereichen, die in einem Sicherheitsschemaobjekt definiert sind, prüft oder erzwingt diese Bereiche jedoch nicht.

Mehrere Sicherheitsanforderungen

Anforderungen an API-Schlüssel: API Gateway unterstützt keine alternativen (logischen ODER) Sicherheitsanforderungen, wenn eines der Schemas ein API-Schlüssel ist. API Gateway unterstützt jedoch Konjunktionen (logisches UND), sodass Sie sowohl einen API-Schlüssel als auch ein OAuth2-Token anfordern können.
OAuth2-Anforderungen: API Gateway unterstützt alternative (logische ODER) Sicherheitsanforderungen für verschiedene OAuth2-Sicherheitsschemas. API Gateway unterstützt keine Konjunktionen (logisches UND), es sei denn, die zusätzliche Sicherheitsanforderung ist ein API-Schlüssel.
Optionale Sicherheit: Sie können eine leere Sicherheitsanforderung (- {}) verwenden, um die Sicherheit für einen API-Schlüssel optional zu machen. API Gateway unterstützt dies jedoch nicht für OAuth.

Validierung der Sicherheitsdefinition

API Gateway lehnt eine OpenAPI 3.x-Spezifikation ab, die eine Sicherheitsanforderung ohne entsprechende Definition im Abschnitt securityDefinitions verwendet.

URL-Pfadvorlagen

API Gateway unterstützt nur URL-Pfadvorlagenparameter, die ganze Pfadsegmente darstellen, z. B. /items/{itemId}. API Gateway unterstützt keine Parameter, die Teilsegmenten entsprechen, z. B. /items/prefix_{id}_suffix, und lehnt diese ab.

Parameter, Schemas, Anfragetexte und Typen

API Gateway akzeptiert OpenAPI-Dokumente mit verschiedenen Parameter- und Typdefinitionen (z. B. required-Parameter und Arrayformate), erzwingt sie jedoch nicht. API Gateway leitet eingehende Anfragen unabhängig von diesen Definitionen an Ihre API weiter.

API Gateway unterstützt nur primitive Typen in Anfrageparametern.

Verweise auf externe Typen

API Gateway unterstützt keine Verweise auf Typen außerhalb des bereitgestellten OpenAPI-Dokuments. Beispielsweise lässt API Gateway keine $ref zu, die auf eine externe URL verweist, und lehnt sie ab.

Benutzerdefinierter Port in der Hostadresse

API Gateway lässt keine benutzerdefinierten Ports im Feld servers.url eines OpenAPI-Dokuments zu.

Einschränkungen für YAML-Aliasse

Ein an API Gateway gesendetes OpenAPI-Dokument kann maximal 200 YAML-Aliasknoten enthalten.