亚马逊AWS官方博客

推出新的 AWS API 模型公开可用资源

现在，我们宣布推出 Amazon Web Services (AWS) API 模型的新公开可用资源。现在，我们每天都会在 Maven Central 上发布 AWS API 模型，并在 GitHub 上的新存储库中提供开源访问。该存储库包含定义 AWS 公共接口定义和行为的 Smithy API 模型的最新权威资源。

这些 Smithy 模型可用于更好地理解 AWS 服务，构建开发人员工具，例如用于连接到 AWS 的自定义软件开发工具包 (SDK) 和命令行界面 (CLI)，或者用于在 AWS 上验证应用程序集成的测试工具。

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

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

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

了解 AWS API 模型

您可以访问 GitHub 上的 api-models-aws 存储库，直接浏览 AWS 服务模型。该存储库包含所有公共 AWS API 服务的采用 JSON AST 格式的 Smithy 模型。所有 Smithy 模型都包含形状和特征。形状是类型的实例，特征用于为形状添加客户端、服务端或文档所需的元数据。

AWS 模型存储库包含：

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

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

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

操作类型表示 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": {}
          }
        ]
      }
    },
JSON

我们广泛使用 Smithy 对服务 API 进行建模，并提供 AWS SDK 和 AWS CLI 的每日发布版本。AWS API 模型有助于实现与 AWS 服务交互的服务器存根。

如何使用 AWS API 模型进行构建

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

我想举两个例子，说明如何使用 AWS API 模型和 Smithy 构建工具自行构建应用程序。

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

现已推出

现在，您可以每天访问 AWS API 模型，在 Maven Central 上提供 AWS API 模型存储库和服务模型包的开源访问权限。您可以使用他们选择的 maven 包导入模型并添加依赖项。

要了解有关 AWS 首选 API 建模语言的更多信息，请访问 Smithy.io 及其代码生成指南。要了解每个 AWS SDK 的更多信息，请访问 Tools to Build on AWS 及其相应的 SDK 特定支持存储库，或通过您的常规 AWS Support 联系方式进行联系。

— Channy

*前述特定亚马逊云科技生成式人工智能相关的服务仅在亚马逊云科技海外区域可用，亚马逊云科技中国仅为帮助您了解行业前沿技术和发展海外业务选择推介该服务。