OpenAPI-Schemaziele
OpenAPI (früher bekannt als Swagger) ist ein weit verbreiteter Standard zur Beschreibung von RESTful-APIs. Gateway unterstützt OpenAPI 3.0-Spezifikationen zur Definition von API-Zielen.
OpenAPI-Ziele verbinden Ihr Gateway mit REST-APIs, die mithilfe von OpenAPI-Spezifikationen definiert wurden. Das Gateway übersetzt eingehende MCP-Anfragen in HTTP-Anfragen an diese APIs und kümmert sich um die Formatierung der Antworten.
Informieren Sie sich über die wichtigsten Überlegungen und Einschränkungen, einschließlich der Funktionsunterstützung, um zu entscheiden, ob ein OpenAPI-Ziel für Ihren Anwendungsfall geeignet ist. Ist dies der Fall, können Sie ein Schema erstellen, das den Spezifikationen entspricht, und dann Berechtigungen einrichten, damit das Gateway auf das Ziel zugreifen kann. Wählen Sie ein Thema aus, um mehr zu erfahren:
Wichtigste Überlegungen und Einschränkungen
Wichtig
Die OpenAPI-Spezifikation muss operationId Felder für alle Operationen enthalten, die Sie als Tools verfügbar machen möchten. Die OperationID wird als Werkzeugname in der MCP-Schnittstelle verwendet.
Beachten Sie bei der Verwendung von OpenAPI-Zielen die folgenden Anforderungen und Einschränkungen:
-
OpenAPI-Versionen 3.0 und 3.1 werden unterstützt (Swagger 2.0 wird nicht unterstützt)
-
Die OpenAPI-Datei muss frei von semantischen Fehlern sein
-
Das Serverattribut muss eine gültige URL des tatsächlichen Endpunkts haben
-
Nur der application/json Inhaltstyp wird vollständig unterstützt
-
Komplexe Schemafunktionen wie OneOf, AnyOf und AllOf werden nicht unterstützt
-
Serialisierer für Pfadparameter und Parameterserialisierer für Abfrage-, Header- und Cookie-Parameter werden nicht unterstützt
-
Für jedes LLM gelten Einschränkungen. ToolSpec Wenn OpenAPI APIs/properties/object Namen hat, die nicht den jeweiligen Downstream-LLMs entsprechen, schlägt die Datenebene fehl. ToolSpec Häufige Fehler sind Eigenschaftsnamen, die die zulässige Länge überschreiten, oder ein Name, der ein Zeichen enthält, das nicht unterstützt wird.
Für beste Ergebnisse mit OpenAPI-Zielen:
-
Beziehen Sie OperationId immer in alle Operationen ein
-
Verwenden Sie einfache Parameterstrukturen anstelle einer komplexen Serialisierung
-
Implementieren Sie Authentifizierung und Autorisierung außerhalb der Spezifikation
-
Verwenden Sie für maximale Kompatibilität nur unterstützte Medientypen
Bewährte Sicherheitsmethoden für URL-Parameter
Warnung
Vermeiden Sie bei der Definition von Server-URLs in Ihren OpenAPI-Spezifikationen die Verwendung zu freizügiger URL-Parametermuster, die Ihr Gateway Sicherheitsrisiken aussetzen könnten.
URL-Parameter in OpenAPI-Serverdefinitionen ermöglichen eine dynamische Endpunktkonfiguration. Bestimmte Muster können jedoch zu Sicherheitslücken führen, wenn sie nicht richtig eingeschränkt werden. Vermeiden Sie insbesondere die Verwendung vollständig dynamischer Domänenmuster wie:
-
https://{yourDomain}/- Erlaubt die willkürliche Ersetzung von Domänen -
https://{subdomain}.{env}.{domain}.com- Mehrere Platzhalter ohne Einschränkungen -
https://{host}/api/- Uneingeschränkter Host-Parameter
Diese Muster können potenziell ausgenutzt werden, um:
-
Leiten Sie Anfragen an unbeabsichtigte oder böswillige Endpunkte weiter
-
Greifen Sie auf interne Netzwerkressourcen zu (Server-Side Request Forgery)
-
Exfiltrieren Sie Anmeldeinformationen oder sensible Daten
Empfohlene Vorgehensweisen:
-
Verwenden Sie nach Möglichkeit vollqualifizierte, statische URLs:
https://api.example.com/v1 -
Beschränken Sie die Parameter auf Subdomänen innerhalb Ihrer kontrollierten Domain und implementieren Sie die Validierung in Ihrer Anwendung
-
Vermeiden Sie die Verwendung von Parametern, die eine willkürliche Domain- oder Host-Substitution ermöglichen
-
Implementieren Sie eine zusätzliche Validierung in Ihrer API, um zu überprüfen, ob die Werte der Laufzeitparameter den erwarteten Mustern entsprechen
AgentCore Gateway validiert automatisch Regionsparameter und blockiert Anfragen an private IP-Bereiche.
Beispiel für eine sichere Server-URL-Konfiguration:
{ "servers": [ { "url": "https://api.example.com/v1" } ] }
Wenn dynamische Parameter erforderlich sind, verwenden Sie vollqualifizierte Domänen mit minimalen Platzhaltern und Enum-Einschränkungen:
{ "servers": [ { "url": "https://{tenant}.api.example.com/v1", "variables": { "tenant": { "default": "default-tenant", "description": "Customer tenant identifier", "enum": ["tenant1", "tenant2", "tenant3"] } } } ] }
Bei diesem Ansatz werden URL-Parameter auf bestimmte Subdomänen innerhalb Ihrer kontrollierten Domain beschränkt und gleichzeitig die Flexibilität für Mehrmandantenbereitstellungen gewahrt. Die Verwendung von Enum-Beschränkungen verhindert willkürliche Werte und trägt zum Schutz vor SSRF-Angriffen bei, indem Parameter auf vordefinierte, sichere Werte beschränkt werden. Überprüfen Sie außerdem immer Mandantenwerte in Ihrer Anwendungslogik.
Wenn Sie erwägen, OpenAPI-Schemaziele mit AgentCore Gateway zu verwenden, lesen Sie die folgende Tabelle zur Funktionsunterstützung.
Unterstützung von OpenAPI-Funktionen
In der folgenden Tabelle sind die OpenAPI-Funktionen aufgeführt, die von Gateway unterstützt und nicht unterstützt werden:
| Unterstützte Funktionen | Nicht unterstützte Funktionen |
|---|---|
|
Schemadefinitionen Grundlegende Datentypen (Zeichenfolge, Zahl, Ganzzahl, Boolean, Array, Objekt) Erforderliche Feldvalidierung Verschachtelte Objektstrukturen Array-Definitionen mit Elementspezifikationen |
Schemazusammensetzung Eine der Spezifikationen Alle OF-Spezifikationen Alle OF-Spezifikationen |
|
HTTP-Methoden Standard-HTTP-Methoden (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) |
Sicherheitsschemata Sicherheitsschemata auf der OpenAPI-Spezifikationsebene (die Authentifizierung muss mithilfe der ausgehenden Autorisierungskonfiguration des Gateways konfiguriert werden) |
|
Medientypen -data -www-form-urlencoded application/json application/xml multipart/form application/x |
Medientypen Benutzerdefinierte Medientypen, die über die Liste der unterstützten Medientypen hinausgehen Binäre Medientypen |
|
Pfadparameter Einfache Pfadparameterdefinitionen (Beispiel: /users/ {userId}) |
Serialisierung von Parametern Komplexe Serialisierer für Pfadparameter (Beispiel: |
|
Abfrageparameter Grundlegende Definitionen von Abfrageparametern Einfache Zeichenfolgen-, Zahlen- und boolesche Typen |
Callbacks und Webhooks Callback-Operationen Webhook-Definitionen |
|
Request/Response Hauptteile JSON-Anforderungs- und Antworttexte XML-Anfrage- und Antworttexte Standard-HTTP-Statuscodes (200, 201, 400, 404, 500 usw.) |
Verbindungen zwischen Vorgängen |
Autorisierungsstrategie
Die folgenden Arten der ausgehenden Autorisierung werden für OpenAPI-Ziele unterstützt:
-
Keine Autorisierung — Das Gateway ruft das OpenAPI-Ziel ohne vorkonfigurierte Autorisierung auf. Dieser Ansatz wird nicht empfohlen.
-
OAuth — Das Gateway unterstützt sowohl zweistufiges OAuth (Grant-Typ Client Credentials) als auch dreibeiniges OAuth (Authorization Code Grant-Typ). Sie konfigurieren den Autorisierungsanbieter in Amazon Bedrock AgentCore Identity in demselben Konto und derselben Region wie das Gateway.
-
API-Schlüssel — Das Gateway verwendet einen API-Schlüssel-Anmeldeinformationsanbieter, um sich beim OpenAPI-Ziel zu authentifizieren. Sie konfigurieren den API-Schlüsselanbieter in Amazon Bedrock AgentCore Identity im selben Konto und in derselben Region wie das Gateway.
-
IAM (AWS Signature Version 4 (Sig V4)) — Das Gateway signiert Anfragen an das OpenAPI-Ziel mithilfe von SigV4 mit den Anmeldeinformationen für die Gateway-Servicerolle. Sie konfigurieren eine
IamCredentialProvidermit einem erforderlichen Dienstnamen für die SigV4-Signierung und einer optionalen Region (standardmäßig die Gateway-Region).
Wichtig
Für die ausgehende IAM-Autorisierung (SigV4) muss das OpenAPI-Ziel hinter einem AWS Dienst gehostet werden, der die IAM-Authentifizierung nativ unterstützt. Das Gateway signiert ausgehende Anfragen mit SigV4, ändert jedoch nicht die Authentifizierungskonfiguration auf dem Ziel. Der Zieldienst muss in der Lage sein, SigV4-Signaturen zu überprüfen.
Die folgenden AWS Dienste unterstützen nativ die IAM-Authentifizierung und sind mit der ausgehenden IAM-Autorisierung für OpenAPI-Ziele kompatibel:
-
Amazon API Gateway
-
URLs für Lambda-Funktionen
-
Amazon Bedrock Gateway AgentCore
Dienste, die SigV4-Signaturen nicht nativ verifizieren, wie Application Load Balancer oder direkte Amazon EC2 EC2-Endpunkte, sind nicht mit der ausgehenden IAM-Autorisierung kompatibel. Wenn Ihr OpenAPI-Ziel hinter einem dieser Dienste gehostet wird, verwenden Sie stattdessen OAuth oder API-Schlüsselautorisierung.
Weitere Informationen zum Einrichten der ausgehenden Autorisierung finden Sie unter Ausgehende Autorisierung für Ihr Gateway einrichten.
OpenAPI-Schemaspezifikation
Die OpenAPI-Spezifikation definiert die REST-API, die Ihr Gateway verfügbar machen wird. Beziehen Sie sich bei der Einrichtung Ihrer OpenAPI-Spezifikation auf die folgenden Ressourcen:
-
Informationen zum Format der OpenAPI-Spezifikation finden Sie unter OpenAPI-Spezifikation
. -
Informationen zu unterstützten und nicht unterstützten Funktionen bei der Verwendung einer OpenAPI-Spezifikation mit AgentCore Gateway finden Sie in der Tabelle unter OpenAPI-Feature-Support. Halten Sie sich an diese Anforderungen, um Fehler bei der Erstellung und dem Aufruf des Ziels zu vermeiden.
Nachdem Sie Ihr OpenAPI-Schema definiert haben, können Sie einen der folgenden Schritte ausführen:
-
Laden Sie es in einen Amazon S3 S3-Bucket hoch und verweisen Sie auf den S3-Standort, wenn Sie das Ziel zu Ihrem Gateway hinzufügen.
-
Fügen Sie die Definition direkt ein, wenn Sie das Ziel zu Ihrem Gateway hinzufügen.
Erweitern Sie einen Abschnitt, um Beispiele für unterstützte und nicht unterstützte OpenAPI-Spezifikationen zu sehen:
Im Folgenden finden Sie ein Beispiel für eine unterstützte OpenAPI-Spezifikation
Beispiel für eine unterstützte OpenAPI-Spezifikation:
{ "openapi": "3.0.0", "info": { "title": "Weather API", "version": "1.0.0", "description": "API for retrieving weather information" }, "servers": [ { "url": "https://api.example.com/v1" } ], "paths": { "/weather": { "get": { "summary": "Get current weather", "description": "Returns current weather information for a location", "operationId": "getCurrentWeather", "parameters": [ { "name": "location", "in": "query", "description": "City name or coordinates", "required": true, "schema": { "type": "string" } }, { "name": "units", "in": "query", "description": "Units of measurement (metric or imperial)", "required": false, "schema": { "type": "string", "enum": ["metric", "imperial"], "default": "metric" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string" }, "temperature": { "type": "number" }, "conditions": { "type": "string" }, "humidity": { "type": "number" } } } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Location not found" } } } } } }
Im Folgenden wird ein weiteres Beispiel für eine unterstützte OpenAPI-Spezifikation gezeigt.
{ "openapi": "3.0.0", "info": { "title": "Search API", "version": "1.0.0", "description": "API for searching content" }, "servers": [ { "url": "https://api.example.com/v1" } ], "paths": { "/search": { "get": { "summary": "Search for content", "operationId": "searchContent", "parameters": [ { "name": "query", "in": "query", "description": "Search query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } } } }, "total": { "type": "integer" } } } } } }, "400": { "description": "Bad request" } } } } } }
Im Folgenden finden Sie ein Beispiel für ein nicht unterstütztes Schema mit oneOf:
{ "oneOf": [ {"$ref": "#/components/schemas/Pencil"}, {"$ref": "#/components/schemas/Pen"} ] }
