介绍亚马逊云科技 API 模型和亚马逊云科技 API 定义的公开资源

今天，我们宣布了亚马逊云科技 API 模型的新公开来源。现在，我们每天都会向 Maven Central 发布亚马逊云科技 API 模型，并提供对 GitHub 上新存储库的开源访问权限。该存储库包含定义亚马逊云科技公共接口定义和行为的 Smithy API 模型的权威最新来源。

这些 Smithy 模型可用于更好地理解亚马逊云科技服务并构建开发人员工具，例如用于连接到亚马逊云科技的自定义 SDK 和命令行接口 (CLI) 或用于验证您在亚马逊云科技上的应用程序集成的测试工具。

自 2018 年以来，我们一直在使用 Smithy 模型生成 SDK 客户端和 CLI 工具。所有亚马逊云科技服务均以 Smithy 为模型，以全面记录 API 合同，包括协议、身份验证、请求和响应类型以及错误等操作和行为。

借助此公共资源，您可以自信地构建和测试可以直接与亚马逊云科技服务集成的应用程序，例如：

生成 SDK 客户端 — 您可以使用 Smithy 工具链生成客户端 SDK 库，无需官方亚马逊云科技开发工具包支持和客户端代码生成器，即可为语言社区构建自己的专用 SDK。
生成 API 实现 — 您可以为特定语言的框架生成服务器存根，甚至可以为 AI 代理生成模型上下文协议 (MCP) 服务器配置。您具有内置验证功能，可确保您遵守自己的 API 标准。
构建自己的开发人员工具 — 您可以在亚马逊云科技之上构建自己的工具，例如模拟测试工具、IAM 策略生成器或用于连接到亚马逊云科技的更高级别的抽象。
了解亚马逊云科技 API 行为 — 您可以简明轻松地调查您的构件，以快速查看和理解 SDK 如何解释 API 调用以及这些调用的预期行为。

了解亚马逊云科技 API 模型
您可以通过访问 api-models-aws 存储库直接在 GitHub 上浏览亚马逊云科技服务模型。该存储库包含所有公共亚马逊云科技 API 服务的采用 JSON AST 格式的 Smithy 模型。所有 Smithy 模型都包含形状和特征。形状是 types 的实例，特征用于向形状添加更多信息，这些信息可能对客户端、服务器或文档有用。

亚马逊云科技模型存储库包含：

顶级服务目录使用服务的命名，其中 <sdk-id> 是模型的 SDKid 的值，小写，空格转换为连字符 <sdk-id>
每个服务目录都包含每个 <version> 服务的一个目录，其中 <version> 是服务形状的版本属性的值。
包含在服务版本目录中，将存在一个名为 <sdk-id>-<version>.json 的模型文件

例如，当您想要在 Amazon EC2 服务中定义 RunInstances API 时，该模型使用 service 类型，即将资源和操作聚合在一起的 API 的入口点。成员引用的形状称为其形状 target。

com.amazonaws.ec2#AmazonEC2": {
      "type": "service",
      "version": "2016-11-15",
      "operations": [
....
        {
          "target": "com.amazonaws.ec2#RunInstances"
        },
....
	  ]

该 operation 类型表示 API 操作的输入、输出、特征和可能的错误。操作形状绑定到资源形状和服务形状。在 IDL 中使用 operation_statement 定义操作。在特征中，您可以找到详细的 API 信息，例如文档、示例等。

"com.amazonaws.ec2#RunInstances": {
      "type": "operation",
      "input": {
        "target": "com.amazonaws.ec2#RunInstancesRequest"
      },
      "output": {
        "target": "com.amazonaws.ec2#Reservation"
      },
      "traits": {
        "smithy.api#documentation": "<p>Launches the specified number of instances using an AMI for which you have....",
        smithy.api#examples": [
          {
            "title": "To launch an instance",
            "documentation": "This example launches an instance using the specified AMI, instance type, security group, subnet, block device mapping, and tags.",
            "input": {
              "BlockDeviceMappings": [
                {
                  "DeviceName": "/dev/sdh",
                  "Ebs": {
                    "VolumeSize": 100
                  }
                }
              ],
              "ImageId": "ami-abc12345",
              "InstanceType": "t2.micro",
              "KeyName": "my-key-pair",
              "MaxCount": 1,
              "MinCount": 1,
              "SecurityGroupIds": [
                "sg-1a2b3c4d"
              ],
              "SubnetId": "subnet-6e7f829e",
              "TagSpecifications": [
                {
                  "ResourceType": "instance",
                  "Tags": [
                    {
                      "Key": "Purpose",
                      "Value": "test"
                    }
                  ]
                }
              ]
            },
            "output": {}
          }
        ]
      }
    },

我们广泛使用 Smithy 对我们的服务 API 进行建模，并提供亚马逊云科技开发工具包和亚马逊云科技 CLI 的每日版本。亚马逊云科技 API 模型有助于实现服务器存根以与亚马逊云科技服务进行交互。

如何使用亚马逊云科技 API 模型构建
Smithy API 模型提供构建工具、客户端或服务器代码生成器、IDE 支持和实现等构建资源。例如，使用 Smithy CLI，您可以轻松构建模型、运行临时验证、比较模型的差异、查询模型等。使用 Smithy CLI，无需设置 Java 或使用 Smithy Gradle 插件即可轻松开始使用 Smithy。

我想展示两个示例，如何使用亚马逊云科技 API 模型和 Smithy 构建工具构建自己的应用程序。

构建一个最小的 SDK 客户端 — 此示例项目提供一个模板，可帮助您开始使用 Smithy TypeScript 为 Amazon DynamoDB 创建最小的亚马逊云科技开发工具包客户端。您可以从 Smithy 模型构建最小的 SDK，然后运行示例代码。要了解更多信息，请访问此处的示例项目。
构建 MCP 服务器 — 此示例项目提供了一个用于生成 fat jar 的模板，其中包含使用 Smithy CLI 运行 MCP StdIO 服务器所需的所有依赖关系。你可以找到通过 MCPServerExample 将工具建模为 Smithy API 来构建 MCP 服务器，也可以为任何 Smithy 服务创建代理 MCP 服务器 ProxyMCPExample。要了解更多信息，请访问 GitHub 存储库。

现已推出
您现在可以每天访问亚马逊云科技 API 模型，提供对 Maven Central 上提供的亚马逊云科技 API 模型存储库和服务模型包的开源访问权限。你可以使用你选择的 maven 包导入模型和添加依赖关系。

要了解有关亚马逊云科技首选 API 建模语言的更多信息，请访问 Smithy.io 及其代码生成指南。要了解每个亚马逊云科技开发工具包的更多信息，请访问在亚马逊云科技上构建工具及其相应的软件开发工具库以获取软件开发工具包的特定支持，或通过您通常的 Amazon Support 联系方式。

— Channy