Amazon Web Services ブログ

AWS API モデルと AWS API 定義のために一般公開されているリソースの紹介

6 月 5 日、Amazon Web Services (AWS) のための API モデルの新しい一般公開ソースについてお知らせします。現在、AWS では AWS API モデルを毎日 Maven Central で公開しており、GitHub にある新しいリポジトリへのオープンソースアクセスを提供しています。このリポジトリには、AWS パブリックインターフェイスの定義と動作を規定する、Smithy API モデルの最終的な最新ソースが含まれています。

これらの Smithy モデルは、AWS サービスに対する理解を深めることに加えて、AWS に接続するためのカスタム Software Development Kit (SDK) やコマンドラインインターフェイス (CLI) といった開発者ツールを構築したり、AWS でのアプリケーション統合を検証するためのテストツールを構築したりするために使用できます。

2018 年以来、AWS では Smithy モデルを使用して SDK クライアントと CLI ツールを生成してきました。すべての AWS サービスは、プロトコル、認証、リクエストとレスポンスタイプ、エラーといった操作や動作を含めた API コントラクトを完全に文書化するために、Smithy でモデル化されています。

このパブリックリソースを使用することで、自信を持って AWS サービスと直接統合できる独自のアプリケーションを構築してテストできます。これには以下が含まれます。

  • SDK クライアントの生成 – Smithy ツールチェーンを使用してクライアント SDK ライブラリを生成することで、公式の AWS SDK サポートやコードジェネレーターを必要とすることなく、言語コミュニティのために独自の専用 SDK を構築できます。
  • API 実装の生成 – 言語固有のフレームワーク用のサーバースタブを生成できます。AI エージェント用の Model Context Protocol (MCP) サーバー構成を生成することも可能です。独自の API 標準に準拠していることを確認するための組み込み検証機能を利用できます。
  • 独自の開発者ツールの構築 – モックテストツール、IAM ポリシージェネレーター、または AWS に接続するためのより高次の抽象化など、AWS 上に独自のツールを構築できます。
  • AWS API 動作の理解 – アーティファクトを簡潔かつ簡単に調査して、SDK が API コールを解釈する方法と、それらのコールで期待される動作をすばやく確認し、理解できます。

AWS API モデルについて学ぶ
AWS サービスモデルは、api-models-aws リポジトリにアクセスすることで、GitHub で直接閲覧できます。このリポジトリには、すべてのパブリック AWS API サービスのための、JSON AST 形式の Smithy モデルが含まれています。すべての Smithy モデルは、シェイプとトレイトで構成されています。シェイプは types のインスタンスです。トレイトは、クライアント、サーバー、文書化に有用であると思われる情報をシェイプに追加するために使用されます。

AWS モデルリポジトリには以下が含まれています。

  • トップレベルのサービスディレクトリは、サービスの <sdk-id> (<sdk-id> はモデルの sdkId の値) を使用して命名されます。名前は小文字で、スペースはハイフンに変換されます。
  • 各サービスディレクトリには、サービスの <version> ごとに 1 つのディレクトリが含まれています。<version> は、サービスシェイプのバージョンプロパティの値です。
  • service-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"
        },
....
	  ]
JSON

operation タイプは、API オペレーションの入力、出力、トレイト、発生する可能性のあるエラーを表します。オペレーションシェイプは、リソースシェイプとサービスシェイプにバインドされます。オペレーションは、operation_statement を使用して IDL で定義されます。トレイトでは、ドキュメントや例などの詳しい 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

AWS は、サービス API をモデル化し、AWS SDK と AWS CLI を毎日リリースするために Smithy を幅広く使用しています。AWS API モデルは、AWS サービスとやり取りするためのサーバースタブの実装に役立ちます。

AWS API モデルを使用して構築する方法
Smithy API モデルは、構築ツール、クライアントまたはサーバーコードジェネレーター、IDE サポート、実装などの構築リソースを提供します。例えば、Smithy CLI では、モデルの構築、アドホック検証の実行、モデル間の相違点の比較、モデルのクエリなどを簡単に行うことができます。Smithy CLI を使用することで、Java をセットアップしたり、Smithy Gradle Plugins を使用したりすることなく、Smithy での作業を簡単に開始できます。

AWS API モデルと Smithy 構築ツールを使用して独自のアプリケーションを構築する方法の例を 2 つご紹介します。

  • 最小限の SDK クライアントを構築する – このサンプルプロジェクトは、Smithy TypeScript を使用して Amazon DynamoDB 用の最小限の AWS SDK クライアントの作成を開始するためのテンプレートを提供します。Smithy モデルから最小限の SDK を構築し、その後でサンプルコードを実行できます。詳細については、こちらのサンプルプロジェクトをご覧ください。
  • MCP サーバーを構築する – このサンプルプロジェクトは、Smithy CLI を使用して MCP StdIO サーバーを実行するために必要なすべての依存関係が含まれる fat jar を生成するためのテンプレートを提供します。ツールを Smithy API としてモデル化することで MCP サーバーを構築するための MCPServerExample や、任意の Smithy サービス用のプロキシ MCP サーバーを作成するための ProxyMCPExample を見つけることができます。 詳細については、GitHub リポジトリをご覧ください。

今すぐご利用いただけます
AWS API モデルリポジトリと、Maven Central で利用できるサービスモデルパッケージへのオープンソースアクセスを提供することで、AWS API モデルに毎日アクセスできるようになりました。選択した Maven パッケージを使用してモデルをインポートし、依存関係を追加することができます。

AWS が優先する API モデリング言語の詳細については、Smithy.io と「Code Generation」ガイドをご覧ください。各 AWS SDK の詳細については、「AWS での構築ツール」と、それぞれのリポジトリにアクセスして SDK 固有のサポートを受けるか、通常の AWS サポート担当者にお問い合わせください。

– Channy

原文はこちらです。