Smithy 模型目標
Smithy 是一種用於定義服務和軟體開發套件 (SDKs) 的語言。Smithy 模型提供比 OpenAPI 更結構化的方式來定義 APIs，對於連線至 AgentCore Gateway 等 AWS 服務特別有用。
Smithy 模型目標會將 AgentCore 閘道連線至使用 Smithy API 模型定義的服務。當您叫用 Smithy 模型閘道目標時，閘道會將傳入的 MCP 請求轉換為傳送至這些服務的 API 呼叫。閘道也會處理回應格式。
檢閱關鍵考量事項和限制，包括功能支援，以協助您決定 Smithy 目標是否適用於您的使用案例。如果是，您可以建立遵循規格的結構描述，然後設定閘道的許可以存取目標。選取主題以進一步了解：
重要考量和限制
搭配 AgentCore Gateway 使用 Smithy 模型時，請注意下列限制：
-
模型大小上限：10MB
-
僅完全支援 JSON 通訊協定繫結
-
僅支援 RestJson 通訊協定
在考慮搭配 AgentCore Gateway 使用 Smithy 模型時，請檢閱下列功能支援資料表。
端點組態的安全最佳實務
警告
在 Smithy 模型中定義端點規則和伺服器 URLs 時，請避免使用過於寬鬆的 URL 參數模式，這些模式可能會讓您的閘道面臨安全風險。
Smithy 模型透過端點規則和 URL 參數支援動態端點組態。不過，如果沒有適當限制，某些模式可能會引入安全漏洞。具體而言，避免使用完全動態模式，例如：
-
端點 URLs主機或網域參數：
https://{host}/api/v1或https://{domain}.example.com -
伺服器 URLs 中的多個未受限預留位置：
https://{subdomain}.{env}.{domain}.com -
允許任意 URL 建構而不進行驗證的端點規則
可能會利用這些模式來：
-
將請求重新導向至非預期或惡意端點
-
存取內部網路資源或執行個體中繼資料服務 （伺服器端請求偽造）
-
滲透 IAM 登入資料或敏感資料
建議實務：
-
盡可能使用靜態、完全合格的端點 URLs
-
對於 AWS 服務，依賴標準端點解析度搭配經過驗證的區域參數。Gateway 會強制執行 AWS 服務 AWS 的區域驗證
-
如果需要自訂端點規則，請將參數限制為特定、已驗證的值
-
避免在 Smithy 模型的端點組態中公開原始主機或網域參數
對於 AWS 服務整合，AgentCore Gateway 會自動驗證區域參數，並封鎖對私有 IP 範圍的請求。
AgentCore Gateway 的 Smithy 功能支援
下表概述 Gateway 支援和不支援的 Smithy 功能：
| 支援的功能 | 不支援的功能 |
|---|---|
|
服務定義 以 Smithy 規格為基礎的服務結構定義 以輸入/輸出形狀為基礎的操作定義 資源定義 特徵形狀 通訊協定支援 RestJson 通訊協定標準 HTTP 請求/回應模式 資料類型 基本類型 （字串、整數、布林值、浮點數、雙） 複雜類型 （結構、清單、映射） 時間戳記處理 Blob 資料類型 HTTP 繫結 基本 HTTP 方法繫結 簡易路徑參數繫結 查詢參數繫結 簡易案例的標頭繫結 端點規則根據條件設定執行期端點判斷 |
通訊協定支援 RestXml 通訊協定 JsonRpc 通訊協定 AwsQuery 通訊協定 Ec2Query 通訊協定 自訂通訊協定 針對特定 APIs 進行多重輸出身分驗證 複雜身分驗證機制需要執行時間決策 操作串流操作 需要自訂通訊協定實作的操作 |
Smithy 模型規格
AgentCore Gateway 為常見 AWS 服務提供內建的 Smithy 模型。若要查看 AWS 服務的 Smithy 模型，請參閱 AWS API 模型儲存庫
注意
AgentCore Gateway 不支援非AWS 服務的自訂 Smithy 模型。
定義 Smithy 模型之後，您可以執行下列其中一項操作：
-
將其上傳至 Amazon S3 儲存貯體，並在您將目標新增至閘道時參考 S3 位置。
-
當您將目標新增至閘道時，將定義內嵌貼上。
展開區段以查看支援和不支援 Smithy 模型規格的範例：
下列範例顯示氣象服務的有效 Smithy 模型規格：
{ "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" } } } } } }
下列範例顯示使用 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"} } ] })
