Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Obiettivi del modello Smithy
Smithy è un linguaggio per la definizione di servizi e kit di sviluppo software (SDK). I modelli Smithy forniscono un approccio più strutturato alla definizione delle API rispetto a OpenAPI e sono particolarmente utili per la connessione a servizi, come Gateway. AWS AgentCore
I target del modello Smithy connettono il AgentCore gateway ai servizi definiti utilizzando i modelli API Smithy. Quando si richiama un target del gateway modello Smithy, il gateway traduce le richieste MCP in entrata in chiamate API inviate a questi servizi. Il gateway gestisce anche la formattazione della risposta.
Esamina le principali considerazioni e limitazioni, incluso il supporto delle funzionalità, per aiutarti a decidere se un target Smithy è applicabile al tuo caso d'uso. In tal caso, puoi creare uno schema che segua le specifiche e quindi impostare le autorizzazioni per consentire al gateway di accedere alla destinazione. Per ulteriori informazioni, scegli un argomento:
Considerazioni e limitazioni principali
Quando utilizzi i modelli Smithy con AgentCore Gateway, tieni presente le seguenti limitazioni:
-
Dimensione massima del modello: 10 MB
-
Sono completamente supportate solo le associazioni al protocollo JSON
-
È supportato solo il protocollo RestJson
Per valutare l'utilizzo dei modelli Smithy con AgentCore Gateway, consulta la seguente tabella di supporto delle funzionalità.
Le migliori pratiche di sicurezza per la configurazione degli endpoint
avvertimento
Quando definisci le regole degli endpoint e gli URL dei server nei tuoi modelli Smithy, evita di utilizzare pattern di parametri URL eccessivamente permissivi che potrebbero esporre il tuo gateway a rischi di sicurezza.
I modelli Smithy supportano la configurazione dinamica degli endpoint tramite regole endpoint e parametri URL. Tuttavia, alcuni modelli possono introdurre vulnerabilità di sicurezza se non sono adeguatamente vincolati. In particolare, evita di utilizzare pattern completamente dinamici come:
-
Parametri di host o dominio illimitati negli URL degli endpoint: o
https://{host}/api/v1https://{domain}.example.com -
Più segnaposti non vincolati negli URL del server:
https://{subdomain}.{env}.{domain}.com -
Regole per gli endpoint che consentono la costruzione arbitraria di URL senza convalida
Questi modelli possono essere potenzialmente sfruttati per:
-
Reindirizza le richieste verso endpoint non intenzionali o dannosi
-
Accedi alle risorse di rete interne o ai servizi di metadati delle istanze (Request Forgery) Server-Side
-
Estrai le credenziali IAM o i dati sensibili
Pratiche consigliate:
-
Utilizza URL di endpoint statici e completamente qualificati quando possibile
-
Per AWS i servizi, affidati alla risoluzione standard degli endpoint con parametri regionali convalidati. Gateway applica la convalida AWS della regione per i servizi AWS
-
Se sono richieste regole personalizzate per gli endpoint, vincola i parametri a valori specifici e convalidati
-
Evita di esporre i parametri grezzi dell'host o del dominio nella configurazione degli endpoint del tuo modello Smithy
Per le integrazioni dei AWS servizi, AgentCore Gateway convalida automaticamente i parametri regionali e blocca le richieste a intervalli IP privati.
Supporto delle funzionalità Smithy per Gateway AgentCore
La tabella seguente illustra le funzionalità di Smithy supportate e non supportate da Gateway:
| Caratteristiche supportate | Caratteristiche non supportate |
|---|---|
|
Definizioni dei servizi Definizioni delle strutture di servizio basate sulle specifiche di Smithy Definizioni delle operazioni con input/output forme Definizioni delle risorse Forme dei tratti RestJson Protocollo di supporto Protocollo di supporto request/response Modelli HTTP standard Tipi di dati Tipi primitivi (string, integer, boolean, float, double) Tipi complessi (strutture, elenchi, mappe) Gestione del timestamp Tipi di dati BLOB Associazioni del metodo HTTP di base Associazioni del metodo HTTP Semplici associazioni di parametri di percorso Semplici Associazioni di parametri di query Header associazioni per casi semplici Endpoint Rules Endpoint Rule Set di regole di runtime Determinazione degli endpoint in base alle condizioni |
Supporto del protocollo di RestXml protocollo JsonRpc AwsQuery protocollo Protocollo Ec2Query Protocolli personalizzati Autenticazione Tipi di autenticazione in uscita multipli per API specifiche Schemi di autenticazione complessi che richiedono decisioni in fase di esecuzione Operazioni di streaming Operazioni che richiedono implementazioni di protocollo personalizzate |
Specifiche del modello Smithy
AgentCore Gateway fornisce modelli Smithy integrati per servizi comuni. AWS Per vedere i modelli Smithy per i AWS servizi, consulta il repository API Models. AWS
Nota
AgentCore Gateway non supporta i modelli Smithy personalizzati per i non servizi.AWS
Dopo aver definito il modello Smithy, puoi effettuare una delle seguenti operazioni:
-
Caricalo in un bucket Amazon S3 e fai riferimento alla posizione S3 quando aggiungi la destinazione al tuo gateway.
-
Incolla la definizione in linea quando aggiungi la destinazione al gateway.
Espandi una sezione per visualizzare esempi di specifiche del modello Smithy supportate e non supportate:
L'esempio seguente mostra una specifica valida del modello Smithy per un servizio meteorologico:
{ "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" } } } } } }
L'esempio seguente mostra una configurazione non valida delle regole degli endpoint utilizzando 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"} } ] })
