OpenAPI スキーマターゲット
OpenAPI (以前は Swagger と呼ばれていました) は、RESTful APIs。Gateway は、API ターゲットを定義するための OpenAPI 3.0 仕様をサポートしています。
OpenAPI ターゲットは、OpenAPI 仕様を使用して定義された REST APIs にゲートウェイを接続します。Gateway は、受信 MCP リクエストをこれらの APIsし、レスポンスのフォーマットを処理します。
OpenAPI ターゲットがユースケースに適しているかどうかを判断するために、機能サポートを含む重要な考慮事項と制限事項を確認してください。その場合は、仕様に従ったスキーマを作成し、ゲートウェイがターゲットにアクセスできるようにアクセス許可を設定できます。詳細情報については、トピックを選択してください。
主な考慮事項と制限事項
重要
OpenAPI 仕様には、ツールとして公開するすべてのオペレーションのoperationIdフィールドを含める必要があります。operationId は MCP インターフェイスのツール名として使用されます。
OpenAPI ターゲットを使用する場合は、次の要件と制限に注意してください。
-
OpenAPI バージョン 3.0 および 3.1 がサポートされています (Swagger 2.0 はサポートされていません)
-
OpenAPI ファイルにはセマンティックエラーがない必要があります
-
サーバー属性には、実際のエンドポイントの有効な URL が必要です
-
アプリケーション/JSON コンテンツタイプのみが完全にサポートされています
-
oneOf、anyOf、allOf などの複雑なスキーマ機能はサポートされていません
-
クエリ、ヘッダー、Cookie パラメータのパスパラメータシリアライザーとパラメータシリアライザーはサポートされていません
-
各 LLM には ToolSpec 制約があります。OpenAPI に、それぞれのダウンストリーム LLM の ToolSpec に準拠していない APIs/properties/object名がある場合、データプレーンは失敗します。 LLMs 一般的なエラーは、プロパティ名が許可された長さを超えているか、サポートされていない文字を含む名前です。
OpenAPI ターゲットで最良の結果を得るには:
-
すべてのオペレーションに operationId を常に含める
-
複雑なシリアル化の代わりにシンプルなパラメータ構造を使用する
-
仕様外の認証と認可を実装する
-
互換性を最大限に高めるには、サポートされているメディアタイプのみを使用してください。
URL パラメータのセキュリティのベストプラクティス
警告
OpenAPI 仕様でサーバー URLs を定義するときは、ゲートウェイをセキュリティリスクにさらす可能性のある過度に寛容な URL パラメータパターンを使用しないでください。
OpenAPI サーバー定義の URL パラメータにより、動的エンドポイント設定が可能になります。ただし、特定のパターンでは、適切に制約されていない場合、セキュリティの脆弱性が発生する可能性があります。具体的には、次のような完全に動的なドメインパターンを使用しないでください。
-
https://{yourDomain}/- 任意のドメイン置換を許可する -
https://{subdomain}.{env}.{domain}.com- 制約のない複数のプレースホルダー -
https://{host}/api/- 無制限のホストパラメータ
これらのパターンは、次の目的で悪用される可能性があります。
-
意図しないエンドポイントまたは悪意のあるエンドポイントにリクエストをリダイレクトする
-
内部ネットワークリソースへのアクセス (サーバー側のリクエスト偽造)
-
認証情報または機密データの流出
推奨されるプラクティス:
-
可能な限り、完全修飾静的 URLs。
https://api.example.com/v1 -
制御されたドメイン内のサブドメインにパラメータを制限し、アプリケーションで検証を実装する
-
任意のドメインまたはホスト置換を許可するパラメータを使用しない
-
API に追加の検証を実装して、ランタイムパラメータ値が予想されるパターンと一致することを確認する
AgentCore Gateway は、リージョンパラメータを自動的に検証し、プライベート IP 範囲へのリクエストをブロックします。
安全なサーバー URL 設定の例:
{ "servers": [ { "url": "https://api.example.com/v1" } ] }
動的パラメータが必要な場合は、プレースホルダーと列挙制限を最小限に抑えた完全修飾ドメインを使用してください。
{ "servers": [ { "url": "https://{tenant}.api.example.com/v1", "variables": { "tenant": { "default": "default-tenant", "description": "Customer tenant identifier", "enum": ["tenant1", "tenant2", "tenant3"] } } } ] }
このアプローチでは、マルチテナントデプロイの柔軟性を維持しながら、URL パラメータを制御対象ドメイン内の特定のサブドメインに制限します。列挙型制限を使用すると、パラメータを事前定義された安全な値に制限することで、任意の値を防ぎ、SSRF 攻撃から保護できます。さらに、アプリケーションロジックで常にテナント値を検証します。
AgentCore Gateway で OpenAPI スキーマターゲットを使用することを検討する際は、次の機能サポートテーブルを確認してください。
OpenAPI 機能のサポート
次の表は、Gateway でサポートされている OpenAPI 機能とサポートされていない OpenAPI 機能の概要を示しています。
| サポートされている機能 | サポートされていない機能 |
|---|---|
|
スキーマ定義 基本的なデータ型 (文字列、数値、整数、ブール値、配列、オブジェクト) 必須フィールド検証 ネストされたオブジェクト構造 項目仕様の配列定義 |
スキーマコンポジション oneOf 仕様 anyOf 仕様 allOf 仕様 |
|
HTTP メソッド 標準 HTTP メソッド (GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS) |
セキュリティスキーム OpenAPI 仕様レベルでのセキュリティスキーム (認証は Gateway のアウトバウンド認可設定を使用して設定する必要があります) |
|
メディアタイプ application/json application/xml multipart/form-data application/x-www-form-urlencoded |
メディアタイプ サポートされているリストを超えるカスタムメディアタイプ バイナリメディアタイプ |
|
パスパラメータ シンプルなパスパラメータ定義 (例: /users/ { userId}) |
パラメータシリアル化 複雑なパスパラメータシリアライザー (例: |
|
クエリパラメータ 基本的なクエリパラメータ定義 単純な文字列、数値、ブール型 |
コールバックと Webhook コールバックオペレーション Webhook 定義 |
|
リクエスト/レスポンス本文 JSON リクエストおよびレスポンス本文 XML リクエストおよびレスポンス本文 標準 HTTP ステータスコード (200、201、400、404、500 など) |
リンク オペレーション間のリンク |
認可戦略
OpenAPI ターゲットでは、次のタイプのアウトバウンド認可がサポートされています。
-
認可なし – ゲートウェイは、事前設定された認可なしで OpenAPI ターゲットを呼び出します。このアプローチはお勧めしません。
-
OAuth – ゲートウェイは、2 レッグの OAuth (クライアント認証情報グラントタイプ) と 3 レッグの OAuth (認可コードグラントタイプ) の両方をサポートします。Amazon Bedrock AgentCore Identity の認可プロバイダーは、ゲートウェイと同じアカウントとリージョンで設定します。
-
API キー – ゲートウェイは、API キー認証情報プロバイダーを使用して OpenAPI ターゲットで認証します。Amazon Bedrock AgentCore Identity の API キープロバイダーは、ゲートウェイと同じアカウントとリージョンで設定します。
-
IAM ( AWS 署名バージョン 4 (Sig V4) ) – ゲートウェイは、ゲートウェイサービスロールの認証情報を使用して SigV4 を使用して OpenAPI ターゲットへのリクエストに署名します。SigV4 署名に必要なサービス名とオプションのリージョン (デフォルトはゲートウェイリージョン)
IamCredentialProviderで を設定します。
重要
IAM (SigV4) アウトバウンド認可では、OpenAPI ターゲットが IAM 認証をネイティブにサポートする AWS サービスの背後でホストされている必要があります。ゲートウェイは SigV4 を使用してアウトバウンドリクエストに署名しますが、ターゲットの認証設定を変更しません。ターゲットサービスは SigV4 署名を検証できる必要があります。
次の AWS サービスは IAM 認証をネイティブにサポートし、OpenAPI ターゲットの IAM アウトバウンド認可と互換性があります。
-
Amazon API Gateway
-
Lambda 関数 URLs
-
Amazon Bedrock AgentCore Gateway
Application Load Balancer や直接 Amazon EC2 エンドポイントなど、SigV4 署名をネイティブに検証しないサービスは、IAM アウトバウンド認可と互換性がありません。OpenAPI ターゲットがこれらのサービスのいずれかの背後でホストされている場合は、代わりに OAuth または API キー認可を使用します。
アウトバウンド認可の設定の詳細については、「ゲートウェイのアウトバウンド認可の設定」を参照してください。
OpenAPI スキーマの仕様
OpenAPI 仕様は、ゲートウェイが公開する REST API を定義します。OpenAPI 仕様を設定するときは、次のリソースを参照してください。
-
OpenAPI 仕様の形式については、OpenAPI 仕様
」を参照してください。 -
AgentCore Gateway で OpenAPI 仕様を使用する場合にサポートされる機能とサポートされない機能については、OpenAPI 機能サポート」の表を参照してください。ターゲットの作成および呼び出し中のエラーを防ぐため、これらの要件に従ってください。
OpenAPI スキーマを定義したら、次のいずれかを実行できます。
-
Amazon S3 バケットにアップロードし、ゲートウェイにターゲットを追加するときに S3 の場所を参照します。
-
ゲートウェイにターゲットを追加するときに、定義をインラインで貼り付けます。
セクションを展開して、サポートされている OpenAPI 仕様とサポートされていない OpenAPI 仕様の例を表示します。
サポートされている OpenAPI 仕様の例を以下に示します。
サポートされている OpenAPI 仕様の例:
{ "openapi": "3.0.0", "info": { "title": "Weather API", "version": "1.0.0", "description": "API for retrieving weather information" }, "servers": [ { "url": "https://api.example.com/v1" } ], "paths": { "/weather": { "get": { "summary": "Get current weather", "description": "Returns current weather information for a location", "operationId": "getCurrentWeather", "parameters": [ { "name": "location", "in": "query", "description": "City name or coordinates", "required": true, "schema": { "type": "string" } }, { "name": "units", "in": "query", "description": "Units of measurement (metric or imperial)", "required": false, "schema": { "type": "string", "enum": ["metric", "imperial"], "default": "metric" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string" }, "temperature": { "type": "number" }, "conditions": { "type": "string" }, "humidity": { "type": "number" } } } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Location not found" } } } } } }
サポートされている OpenAPI 仕様の別の例を次に示します。
{ "openapi": "3.0.0", "info": { "title": "Search API", "version": "1.0.0", "description": "API for searching content" }, "servers": [ { "url": "https://api.example.com/v1" } ], "paths": { "/search": { "get": { "summary": "Search for content", "operationId": "searchContent", "parameters": [ { "name": "query", "in": "query", "description": "Search query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } } } }, "total": { "type": "integer" } } } } } }, "400": { "description": "Bad request" } } } } } }
以下は、oneOf でサポートされていないスキーマの例です。
{ "oneOf": [ {"$ref": "#/components/schemas/Pencil"}, {"$ref": "#/components/schemas/Pen"} ] }
