Ziele des Modells Smithy
Smithy ist eine Sprache zur Definition von Diensten und Software Development Kits (SDKs). Smithy-Modelle bieten im Vergleich zu OpenAPI einen strukturierteren Ansatz zur Definition von APIs und eignen sich besonders für Verbindungen zu AWS Diensten wie AgentCore Gateway.
Ziele des Smithy-Modells verbinden Ihr AgentCore Gateway mit Diensten, die mithilfe von Smithy-API-Modellen definiert wurden. Wenn Sie ein Gateway-Ziel des Modells Smithy aufrufen, übersetzt das Gateway eingehende MCP-Anfragen in API-Aufrufe, die an diese Dienste gesendet werden. Das Gateway kümmert sich auch um die Formatierung der Antwort.
Informieren Sie sich über die wichtigsten Überlegungen und Einschränkungen, einschließlich der Unterstützung von Funktionen, damit Sie entscheiden können, ob ein Smithy-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
Beachten Sie bei der Verwendung von Smithy-Modellen mit AgentCore Gateway die folgenden Einschränkungen:
-
Maximale Modellgröße: 10 MB
-
Nur JSON-Protokollbindungen werden vollständig unterstützt
-
Es wird nur RestJson das Protokoll unterstützt
Wenn Sie erwägen, Smithy-Modelle mit AgentCore Gateway zu verwenden, schauen Sie sich die folgende Tabelle zur Funktionsunterstützung an.
Bewährte Sicherheitsmethoden für die Endpunktkonfiguration
Warnung
Vermeiden Sie bei der Definition von Endpunktregeln und Server-URLs in Ihren Smithy-Modellen die Verwendung zu freizügiger URL-Parametermuster, die Ihr Gateway Sicherheitsrisiken aussetzen könnten.
Smithy-Modelle unterstützen die dynamische Endpunktkonfiguration mithilfe von Endpunktregeln und URL-Parametern. 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 Muster wie:
-
Uneingeschränkte Host- oder Domänenparameter in Endpunkt-URLs:
https://{host}/api/v1oderhttps://{domain}.example.com -
Mehrere uneingeschränkte Platzhalter in Server-URLs:
https://{subdomain}.{env}.{domain}.com -
Endpunktregeln, die die Erstellung beliebiger URLs ohne Überprüfung ermöglichen
Diese Muster können potenziell ausgenutzt werden, um:
-
Leiten Sie Anfragen an unbeabsichtigte oder böswillige Endpunkte weiter
-
Greifen Sie auf interne Netzwerkressourcen oder Instanz-Metadatendienste zu (Server-Side Request Forgery)
-
Exfiltrieren Sie IAM-Anmeldeinformationen oder sensible Daten
Empfohlene Vorgehensweisen:
-
Verwenden Sie nach Möglichkeit statische, vollständig qualifizierte Endpunkt-URLs
-
Verlassen Sie sich bei AWS Diensten auf die standardmäßige Endpunktauflösung mit validierten Regionsparametern. Gateway erzwingt die AWS Regionsvalidierung für Dienste AWS
-
Wenn benutzerdefinierte Endpunktregeln erforderlich sind, beschränken Sie die Parameter auf bestimmte, validierte Werte
-
Vermeiden Sie es, unverarbeitete Host- oder Domänenparameter in der Endpunktkonfiguration Ihres Smithy-Modells offenzulegen
Bei AWS Serviceintegrationen validiert AgentCore Gateway automatisch Regionsparameter und blockiert Anfragen an private IP-Bereiche.
Smithy-Funktionsunterstützung für Gateway AgentCore
In der folgenden Tabelle sind die Funktionen von Smithy aufgeführt, die von Gateway unterstützt und nicht unterstützt werden:
| Unterstützte Funktionen | Nicht unterstützte Funktionen |
|---|---|
|
Dienstdefinitionen Servicestrukturdefinitionen auf der Grundlage von Smithy-Spezifikationen Operationsdefinitionen mit input/output Formen Ressourcendefinitionen Merkmalsformen RestJson Protokollunterstützungsprotokoll request/response Standard-HTTP-Muster Datentypen Primitive Typen (Zeichenfolge, Ganzzahl, Boolean, Float, Double) Komplexe Typen (Strukturen, Listen, Maps) Zeitstempelbehandlung Blob-Datentypen HTTP-Bindungen Grundlegende HTTP-Methodenbindungen Einfache Pfadparameterbindungen Abfrageparameterbindungen Header-Bindungen für einfache Fälle Endpunktregeln Endpunktregeln Endpunktregelsätze Bestimmung von Laufzeitendpunkten auf der Grundlage von Bedingungen |
Protokollunterstützung RestXml JsonRpc Protokollprotokoll AwsQuery Ec2Query-Protokoll Benutzerdefinierte Protokolle Authentifizierung Mehrere Ausgangsauthentifizierungstypen für bestimmte APIs Komplexe Authentifizierungsschemata, die Laufzeitentscheidungen erfordern Operationen Streaming-Operationen, die benutzerdefinierte Protokollimplementierungen erfordern |
Spezifikation des Smithy-Modells
AgentCore Gateway bietet integrierte Smithy-Modelle für gängige AWS Dienste. Smithy-Modelle für AWS Dienste finden Sie im AWS API-Models-Repository.
Anmerkung
AgentCore Gateway unterstützt keine benutzerdefinierten Smithy-Modelle für Nichtdienste.AWS
Nachdem Sie Ihr Smithy-Modell 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 Modellspezifikationen von Smithy zu sehen:
Das folgende Beispiel zeigt eine gültige Smithy-Modellspezifikation für einen Wetterdienst:
{ "smithy": "2.0", "metadata": { "suppressions": [] }, "shapes": { "example.weather#WeatherService": { "type": "service", "version": "1.0.0", "operations": [ { "target": "example.weather#GetCurrentWeather" } ], "traits": { "aws.protocols#restJson1": {}, "smithy.api#documentation": "Weather service for retrieving weather information" } }, "example.weather#GetCurrentWeather": { "type": "operation", "input": { "target": "example.weather#GetCurrentWeatherInput" }, "output": { "target": "example.weather#GetCurrentWeatherOutput" }, "errors": [ { "target": "smithy.framework#ValidationException" } ], "traits": { "smithy.api#http": { "method": "GET", "uri": "/weather" }, "smithy.api#documentation": "Get current weather for a location" } }, "example.weather#GetCurrentWeatherInput": { "type": "structure", "members": { "location": { "target": "smithy.api#String", "traits": { "smithy.api#required": {}, "smithy.api#httpQuery": "location", "smithy.api#documentation": "City name or coordinates" } }, "units": { "target": "example.weather#Units", "traits": { "smithy.api#httpQuery": "units", "smithy.api#default": "metric", "smithy.api#documentation": "Units of measurement (metric or imperial)" } } } }, "example.weather#GetCurrentWeatherOutput": { "type": "structure", "members": { "location": { "target": "smithy.api#String", "traits": { "smithy.api#documentation": "Location name" } }, "temperature": { "target": "smithy.api#Float", "traits": { "smithy.api#documentation": "Current temperature" } }, "conditions": { "target": "smithy.api#String", "traits": { "smithy.api#documentation": "Weather conditions description" } }, "humidity": { "target": "smithy.api#Float", "traits": { "smithy.api#documentation": "Humidity percentage" } } } }, "example.weather#Units": { "type": "enum", "members": { "metric": { "target": "smithy.api#Unit", "traits": { "smithy.api#enumValue": "metric" } }, "imperial": { "target": "smithy.api#Unit", "traits": { "smithy.api#enumValue": "imperial" } } } } } }
Das folgende Beispiel zeigt eine ungültige Konfiguration von Endpunktregeln mit Smithy:
@endpointRuleSet({ "rules": [ { "conditions": [{"fn": "booleanEquals", "argv": [{"ref": "UseFIPS"}, true]}], "endpoint": {"url": "https://weather-fips.{Region}.example.com"} }, { "endpoint": {"url": "https://weather.{Region}.example.com"} } ] })
