ターゲットとしての Amazon API Gateway REST API ステージ

API Gateway REST API ターゲットは、ゲートウェイを REST API のステージに接続します。ゲートウェイは、受信 MCP リクエストを REST API への HTTP リクエストに変換し、レスポンスのフォーマットを処理します。API Gateway ターゲットを追加または更新すると、AgentCore Gateway はユーザーに代わって API Gateway の GetExport API を呼び出します。

ターゲット設定でツールフィルターとツールオーバーライドを指定できます。ツールフィルターを使用すると、特定のリソースパスと HTTP メソッドの組み合わせをゲートウェイのツールとして使用できます。これらのフィルターは、ツールとして指定したオペレーションのみを公開する許可リストを作成します。

API Gateway コンソールから、API Gateway REST API ステージをゲートウェイターゲットとして設定することもできます。詳細については、Amazon API Gateway ドキュメントのAgentCore ゲートウェイにステージを追加する」を参照してください。

主な考慮事項と制限事項

API Gateway REST API ステージをターゲットとして使用する場合は、次の要件と制限に注意してください。

API Gateway ツールの設定

API Gateway REST API をゲートウェイターゲットとして追加する場合は、API Gateway ツール設定を指定する必要があります。API Gateway ツール設定は、REST API のどのオペレーションをツールとして公開するかを定義します。公開するオペレーションを選択するにはツールフィルターのリストが必要で、オプションでツールの上書きを受け入れて、ツール名や説明などのツールメタデータをカスタマイズします。

ツールフィルター

ツールフィルターを使用すると、パスとメソッドの組み合わせを使用して REST API オペレーションを選択できます。各フィルターは 2 つのパスマッチング戦略をサポートしています。

各フィルターは、パスと HTTP メソッドのリストの両方を指定します。フィルターは、API に存在する一致する組み合わせに解決されます。複数のフィルターが重複する可能性があり、重複は自動的に重複解除されます。

ツールのオーバーライド

デフォルトでは、MCP ツール名は、フィルターに一致するパスとメソッドの組み合わせoperationIdごとに から取得されます。フィルター一致operationId用の がない場合は、名前を提供する対応するツールオーバーライドが必要です。operationId とオーバーライド名の両方がない場合、ターゲットの作成と更新は検証に失敗します。AgentCore Gateway のツール名の詳細については、AgentCore Gateway ツールの名前を理解する」を参照してください。

ツールの上書きはオプションです。これにより、フィルタリング後に特定のオペレーションのツール名または説明をカスタマイズできます。各オーバーライドでは、明示的なパスと単一の HTTP メソッドを指定する必要があります。ワイルドカードがサポートされていません。オーバーライドは、API に存在するオペレーションと一致し、フィルターによって解決されたオペレーションのいずれかに対応する必要があります。選択されていないオペレーションを上書きすることはできません。を出力するオペレーションからのインポートでエラーが発生した場合は、代わりにツールオーバーライドoperationIdを使用できます。

API Gateway ツール設定の例

次の API Gateway ツール設定の例は、フィルターとオーバーライドを使用する方法を示しています。すべての例では、以下のパスとメソッドで API を使用します。

/pets/{petId} - GET
/pets/{petId}  - POST
/pets/{petId}  - OPTIONS
/pets          - GET
/pets          - OPTIONS
/              - GET

ワイルドカードパスとメソッドのリスト

ツール設定:

{
  "filterPath": "/pets/*",
  "methods": ["GET", "POST"]
}

結果

メソッドの明示的なパスとリスト

ツール設定:

{
  "filterPath": "/pets/{petId}",
  "methods": ["GET", "POST"]
}

結果

明示的なパスと明示的なメソッドのリスト (最も具体的)

ツール設定:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["POST"]
    },
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    }
  ]
}

結果

明示的なパスとワイルドカードパスを混在させて一致させます。

ツール設定:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    },
    {
        "filterPath": "/*",
        "methods": ["GET"]
    }
  ]
}

結果

ツールフィルターとツールオーバーライド

ツールフィルターを指定し、オーバーライドを追加できます。オーバーライドは、/pets などの REST API のリソースパスと、指定されたパスに対して公開する HTTP メソッドを指定します。オーバーライドは、REST API の既存のパスと明示的に一致する必要があります。

ツール設定

{
  "toolFilters": [
    {
      "filterPath": "/pets/*",
      "methods": ["GET", "POST"]
    },
    {
      "filterPath": "/",
      "methods": ["GET"]
    }
  ],
  "toolOverrides": [
    {
      "path": "/pets/{petId}",
      "method": "GET",
      "name": "GetPetById",
      "description": "Retrieve a specific pet by its ID"
    }
  ]
}

結果

API Gateway のエクスポート

API Gateway ターゲットをセットアップするために、AgentCore Gateway はユーザーに代わって API Gateway の GetExport オペレーションを呼び出し、API 定義の OpenAPI 3.0 形式のエクスポートを取得します。これにより、ゲートウェイは受信 MCP リクエストを HTTP リクエストに適切に変換し、レスポンスを処理することができます。AgentCore Gateway が GetExport オペレーションを呼び出す場合の考慮事項は次のとおりです。

REST API での operationId の更新

REST API を更新して、GetExport によって返される OpenAPI 定義が operationId に設定されていることを確認できます。これは、ツールオーバーライドを提供する代替手段です。次に、 を設定する 2 つの方法について説明しますoperationId。

OpenAPI 定義を更新して operationID を設定する OpenAPI

デプロイされた API ステージから OpenAPI 定義をエクスポートするには、GetExport を呼び出し、欠落しているオペレーションを更新し、API operationId を再インポートします。

REST API の メソッドを更新operationIdして を設定する

API Gateway メソッドを設定して、UpdateMethod コマンドoperationNameを使用して を追加できます。API がエクスポートされると、 は operationNameになりますoperationId。

API Gateway API でサポートされているアウトバウンド認可方法

アウトバウンド認証を使用して API を呼び出すように AgentCore Gateway ターゲットを設定できます。

AgentCore Gateway は、API Gateway ターゲットに対して次のタイプのアウトバウンド認可をサポートしています。

詳細については、「ゲートウェイのアウトバウンド認可を設定する」を参照してください。

IAM アウトバウンド認可

API Gateway を使用すると、IAM で REST API を保護できます。IAM 認可が有効になっている場合、クライアントは署名バージョン 4 (SigV4 または SigV4a) を使用して AWS 認証情報でリクエストに署名する必要があります。

IAM アウトバウンド認可を設定するには

API Gateway リソースポリシー

API Gateway リソースポリシーは、指定したプリンシパルが API を呼び出すことができるかどうかを制御するために API Gateway REST API にアタッチする JSON ポリシードキュメントです。AgentCore Gateway がリソースポリシーを使用して REST API を呼び出すには、以下を実行する必要があります。

以下は、AgentCore Gateway に REST API へのアクセスを許可する API リソースポリシーの例です。

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:us-west-2:111122223333:abcd123/*/*/*",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske"
        }
      }
    }
  ]
}

API キーアウトバウンド認可

API キーを使用してアウトバウンド認可を設定するには、AgentCore Identity サービスを使用して認証情報プロバイダーを作成し、API Gateway を介して 用に設定した API キーを使用します。

API キーのアウトバウンド認可を設定するには