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

Funktionseinschränkungen bei OpenAPI 3.x

In diesem Dokument werden die Einschränkungen bei der Verwendung von OpenAPI 3.x mit API Gateway beschrieben.

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

Neue Einschränkungen für OpenAPI 3.x

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

Server

OpenAPI 3.x unterstützt mehrere server-Objekte zum Definieren von Hosts und Basispfaden. 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 gültig für API Gateway:

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 enthalten. Der Basispfad kann sich je nach 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. Das unterscheidet sich vom Standardverhalten von OpenAPI, bei dem relative URLs anhand des Servers aufgelöst werden, auf dem die OpenAPI-Definition gehostet wird. API Gateway behandelt url: /v1 beispielsweise als Basispfad.

Basispfade müssen mit „/“ beginnen. API Gateway lehnt URLs ab, die kein Schema haben oder 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 maximale Gesamtgröße von 10 MB und eine maximale Anzahl von 50 Dateien für hochgeladene OpenAPI 3.x-Dateien.

Einschränkungen von MCP

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

Beschränkung der Anzahl der Tools: Kunden können pro Gateway maximal 1.000 MCP-Tools verwenden.
HTTP-Methoden: Nur Vorgänge vom Typ GET, POST, PUT, PATCH und DELETE können als MCP-Tools bereitgestellt werden. HEAD, OPTIONS und TRACE werden nicht unterstützt.
Streaming: Das SSE-Streaming (Server-Sent Events) von Tool-Aufrufen mit langer Ausführungszeit wird nicht unterstützt.
Batchanfragen: JSON-RPC-Batcharrays werden abgelehnt.
Multimodale Nutzlasten: Tool-Antworten 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: Spezialisierte Methoden wie resources/*, prompts/*, sampling/*, completion/*, ping und logging/* werden nicht unterstützt und geben den JSON-RPC-Fehlercode -32601 zurück.
Keine Tool-Anmerkungen: Hinweise wie destructiveHint oder readOnlyHint werden in Tool-Deklarationen nicht ausgegeben.
CORS-Preflight: Die automatische Verarbeitung von CORS-Preflights (OPTIONS-Anfragen) für den Pfad /mcp wird nicht vom Gateway verwaltet.
Gegenseitiger Ausschluss von Modellrouting: Sie können MCP und Modellrouting nicht in derselben API-Konfiguration verwenden.
Nicht unterstützte MCP-Antworten: Vorgänge, bei denen in der Antwort leere Texte zurückgegeben werden, z. B. HTTP 204-Antworten, werden nicht unterstützt.
Schemaermittlung: Komplexe, verschachtelte Objektschemas, die aus Ihrer OpenAPI-Spezifikation abgeleitet werden, werden aufgrund einer bekannten Einschränkung bei der Konfigurationsverarbeitung möglicherweise nicht vollständig oder korrekt in der tools/list-Ermittlungsantwort gerendert.

Bestehende Einschränkungen

In diesem Abschnitt werden Einschränkungen aus OpenAPI 2.0 beschrieben, die 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, in der eine Sicherheitsanforderung ohne entsprechende Definition im Abschnitt securityDefinitions verwendet wird.

URL-Pfadvorlagen

API Gateway unterstützt nur URL-Pfadvorlagenparameter, die ganze Pfadsegmente darstellen, z. B. /items/{itemId}. API Gateway unterstützt keine Parameter, die sich auf Teilsegmente beziehen, und lehnt sie ab, z. B. /items/prefix_{id}_suffix.

Parameter, Schemas, Anfragetexte und Typen

API Gateway akzeptiert OpenAPI-Dokumente mit verschiedenen Parameter- und Typdefinitionen (z. B. required-Parameter und Array-Formate), erzwingt sie aber 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. API Gateway lässt beispielsweise 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-Alias-Knoten enthalten.