本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Smithy 模型目标
<a name="gateway-building-smithy-targets"></a>

Smithy 是一种用于定义服务和软件开发套件 (SDK) 的语言。与 OpenAPI 相比，Smithy 模型提供了一种更结构化的 API 定义方法，对于连接网关等 Amazon AgentCore 服务特别有用。

Smithy 模型目标将您的 AgentCore 网关连接到使用 Smithy API 模型定义的服务。当您调用 Smithy 模型网关目标时，网关会将传入的 MCP 请求转换为发送到这些服务的 API 调用。网关还处理响应格式。

查看关键注意事项和限制，包括功能支持，以帮助您决定 Smithy 目标是否适用于您的用例。如果是，则可以创建符合规范的架构，然后为网关设置访问目标的权限。选择一个主题以了解更多信息：

**Topics**
+ [主要注意事项和局限性](#gateway-building-smithy-considerations)
+ [Smithy 型号规格](#gateway-smithy-models)

## 主要注意事项和局限性
<a name="gateway-building-smithy-considerations"></a>

在 AgentCore Gateway 中使用 Smithy 模型时，请注意以下限制：
+ 最大模型大小：10MB
+ 仅完全支持 JSON 协议绑定
+ 仅支持 RestJson 协议

在考虑在 AgentCore Gateway 中使用 Smithy 模型时，请查看以下功能支持表。

### 端点配置的安全最佳实践
<a name="gateway-smithy-url-security"></a>

**警告**  
在 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
+ 对于 Amazon 服务，依赖标准终端节点解析和经过验证的区域参数。Gateway 强制对 Amazon 服务进行 Amazon 区域验证
+ 如果需要自定义端点规则，请将参数限制为经过验证的特定值
+ 避免在 Smithy 模型的端点配置中暴露原始主机或域名参数

对于 Amazon 服务集成， AgentCore Gateway 会自动验证区域参数并阻止对私有 IP 范围的请求。

### 对网关的 Smithy 功能支持 AgentCore
<a name="gateway-schema-smithy-features"></a>

下表概述了 Gateway 支持和不支持的 Smithy 功能：


| 支持的功能 | 不支持的特征 | 
| --- | --- | 
|  ****服务定义基于 Smithy 规范的服务结构定义使用 input/output 形状的操作定义资源定义特征形状**协议支持** RestJson 协议标准 HTTP request/response 模式**数据类型**原始类型（字符串、整数、布尔值、浮点数、双精度）复杂类型（结构、列表、地图）时间戳处理 Blob 数据类型 ** HTTP 绑定基**本 HTTP 方法绑定简单路径参数绑定查询参数绑定标头简单案例的绑定**端点规则**端点规则设置基于条件的运行时端点确定 |  **协议支持** RestXml 协议协议 JsonRpc AwsQuery 协议 Ec2Query 协议自定义协议**身份验证特定 API 的**多种出口身份验证类型需要运行时决策的复杂身份验证方案**操作**流式操作需要自定义协议实现的操作 | 

## Smithy 型号规格
<a name="gateway-smithy-models"></a>

AgentCore Gateway 为常见 Amazon 服务提供内置的 Smithy 模型。要查看 Smithy Amazon 服务模型，请参阅 [Amazon API 模型存储库](https://github.com/aws/api-models-aws)。

**注意**  
AgentCore Gateway 不支持针对非Amazon 服务的自定义 Smithy 模型。

定义 Smithy 模型后，可以执行以下操作之一：
+ 将其上传到 Amazon S3 存储桶，并在将目标添加到网关时参考 S3 位置。
+ 将目标添加到网关时，将定义粘贴到内联中。

展开一节，查看支持和不支持的 Smithy 型号规格示例：

### 示例：气象服务的有效 Smithy 模型
<a name="gateway-smithy-model-spec-valid"></a>

以下示例显示了气象服务的有效 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 模型规格无效
<a name="gateway-smithy-model-spec-invalid"></a>

以下示例显示了使用 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"}
    }
  ]
})
```