本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
Smithy 模型目标
Smithy 是一种用于定义服务和软件开发套件 (SDK) 的语言。与 OpenAPI 相比，Smithy 模型提供了一种更结构化的 API 定义方法，对于连接网关等 AWS AgentCore 服务特别有用。
Smithy 模型目标将您的 AgentCore 网关连接到使用 Smithy API 模型定义的服务。当您调用 Smithy 模型网关目标时，网关会将传入的 MCP 请求转换为发送到这些服务的 API 调用。网关还处理响应格式。
查看关键注意事项和限制，包括功能支持，以帮助您决定 Smithy 目标是否适用于您的用例。如果是，则可以创建符合规范的架构，然后为网关设置访问目标的权限。选择一个主题以了解更多信息：
主要注意事项和局限性
在 AgentCore Gateway 中使用 Smithy 模型时，请注意以下限制：
-
最大模型大小：10MB
-
仅完全支持 JSON 协议绑定
-
仅支持 RestJson 协议
在考虑在 AgentCore Gateway 中使用 Smithy 模型时，请查看以下功能支持表。
端点配置的安全最佳实践
警告
在 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 方法绑定简单路径参数绑定查询参数绑定标头简单案例的绑定端点规则端点规则设置基于条件的运行时端点确定 |
协议支持 RestXml 协议协议 JsonRpc AwsQuery 协议 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"} } ] })
