Smithy 模型目标
Smithy 是一种用于定义服务和软件开发套件 (SDK) 的语言。与 OpenAPI 相比，Smithy 模型提供了一种更具结构化的 API 定义方法，对于连接 AWS 服务（例如 AgentCore 网关）特别有用。
Smithy 模型目标将您的 AgentCore 网关连接到使用 Smithy API 模型定义的服务。当您调用 Smithy 模型网关目标时，网关会将传入的 MCP 请求转换为发送到这些服务的 API 调用。网关还处理响应格式。
查看关键注意事项和限制，包括功能支持，以帮助您决定 Smithy 目标是否适用于您的用例。如果是，则可以创建符合规范的架构，然后为网关设置访问目标的权限。选择一个主题以了解更多信息：
主要考虑因素和限制
将 Smithy 模型与 AgentCore Gateway 配合使用时，请注意以下限制：
-
最大模型大小：10MB
-
仅完全支持 JSON 协议绑定
-
仅支持 RestJson 协议
在考虑将 Smithy 模型与 AgentCore Gateway 配合使用时，请查看以下功能支持表。
端点配置的安全最佳实践
警告
在 Smithy 模型中定义端点规则和服务器 URL 时，请避免使用过于宽松的 URL 参数模式，因为这可能会使您的网关面临安全风险。
Smithy 模型支持通过端点规则和 URL 参数进行动态端点配置。但是，如果限制不当，某些模式可能会引入安全漏洞。具体而言，请避免使用完全动态的模式，例如：
-
终端节点 URL 中的主机或域名参数不受限制：
https://{host}/api/v1或https://{domain}.example.com -
服务器 URL 中有多个不受限制的占位符：
https://{subdomain}.{env}.{domain}.com -
允许在不进行验证的情况下构造任意 URL 的端点规则
这些模式有可能被利用来：
-
将请求重定向到非预期或恶意终端节点
-
访问内部网络资源或实例元数据服务（Server-Side 请求伪造）
-
泄露 IAM 凭证或敏感数据
推荐做法：
-
尽可能使用静态、完全限定的端点 URL
-
对于 AWS 服务，请依靠带有经过验证的区域参数的标准端点解析。Gateway 强制对 AWS 服务进行 AWS 区域验证
-
如果需要自定义端点规则，请将参数限制为经过验证的特定值
-
避免在 Smithy 模型的端点配置中暴露原始主机或域参数
对于 AWS 服务集成， AgentCore Gateway 会自动验证区域参数并阻止对私有 IP 范围的请求。
网关支持 Smithy 功能 AgentCore
下表概述了 Gateway 支持和不支持的 Smithy 功能：
| 支持的功能 | 不支持的特征 |
|---|---|
|
服务定义基于 Smithy 规范的服务结构定义带 input/output 形状的操作定义资源定义特征形状 RestJson 协议支持协议标准 HTTP request/response 模式数据类型原始类型（字符串、整数、布尔值、浮点数、双精度）复杂类型（结构、列表、地图）时间戳处理 Blob 数据类型 HTTP 绑定基本 HTTP 方法绑定简单路径参数绑定查询参数绑定简单案例的标头绑定 端点规则端点规则设置基于条件的运行时端点确定 |
P@@ ro toco RestXml l Su AwsQuery pport JsonRpc 协议协议协议 Ec2Query 协议自定义协议身份验证特定 API 的多种出口身份验证类型需要运行时决策的复杂身份验证方案操作流操作需要自定义协议实现的操作 |
Smithy 模型规格
AgentCore Gateway 为常见 AWS 服务提供了内置的 Smithy 模型。要查看 Smithy 的 AWS 服务模型，请参阅 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"} } ] })
