API Gateway で WebSocket API 統合レスポンスを設定する - Amazon API Gateway
統合レスポンスの概要双方向通信の統合レスポンスAPI Gateway コンソールを使用した統合レスポンスの設定AWS CLI を使用して統合レスポンスを設定する

API Gateway で WebSocket API 統合レスポンスを設定する

次のセクションでは、WebSocket API の統合レスポンスの概要を示し、WebSocket API の統合レスポンスを設定する方法について説明します。

統合レスポンスの概要

API Gateway の統合レスポンスとは、バックエンドサービスからのレスポンスをモデル化および操作するための方法です。REST API と WebSocket API 統合レスポンスの設定にはいくつかの違いがありますが、概念的には同じ動作です。

WebSocket ルートは、双方向または単方向通信に対して設定できます。

  • ルートが双方向通信用に設定されている場合、REST API の統合レスポンスと同様に、統合レスポンスにより、返されたメッセージペイロードで変換を設定できます。

  • ルートが単方向通信用に設定されている場合、統合レスポンスの設定に関係なく、メッセージの処理後に WebSocket チャネル経由でレスポンスは返されません。

ユーザーがルートレスポンスを設定しない限り、API Gateway はルートレスポンスにバックエンドレスポンスを渡しません。ルートレスポンスの詳しい設定方法については、「API Gateway で WebSocket API のルートレスポンスを設定する」を参照してください。

双方向通信の統合レスポンス

統合はプロキシ統合と非プロキシ統合に分割することができます。

重要

プロキシ統合では、API Gateway は自動的にバックエンド出力を完全なペイロードとして発信者に渡します。統合レスポンスは発生しません。

非プロキシ統合の場合、少なくとも 1 つの統合レスポンスを設定する必要があります。

  • 明示的な選択が行われなかった場合、いずれかの統合レスポンスがキャッチオールとして機能することが理想的です。このデフォルトのケースは、統合レスポンスキー $default を設定することにより表されます。

  • 他のいずれの場合も、統合レスポンスキーは正規表現として機能します。これは、"/expression/" の形式に従う必要があります。

非プロキシ HTTP 統合の場合:

  • API Gateway は、バックエンドレスポンスの HTTP ステータスコードへの一致を試みます。この場合、統合レスポンスキーは正規表現として機能します。一致が見つからない場合、$default が統合レスポンスとして選択されます。

  • テンプレート選択式も、前述したように同様に機能します。例:

    • /2\d\d/: 成功のレスポンスを受信して変換

    • /4\d\d/: 不正なリクエストエラーを受信して変換

    • $default: すべての予期しないレスポンスを受信して変換

テンプレート選択式の詳細については、「テンプレート選択式」を参照してください。

API Gateway コンソールを使用した統合レスポンスの設定

API Gateway コンソールを使用して WebSocket API のルート統合レスポンスを設定するには

  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. WebSocket API を選択し、ルートを選択します。

  3. [統合リクエスト] タブを選択してから、[統合リクエスト設定] セクションで [統合レスポンスの作成] を選択します。

  4. [レスポンスキー] に、レスポンス選択式を評価した後で、送信メッセージのレスポンスキーに表示される値を入力します。たとえば、/4\d\d/ を入力して不正なリクエストエラーを受信して変換したり、$default を入力してテンプレート選択式に一致するすべてのレスポンスを受信して変換したりできます。

  5. [テンプレート選択式] には、送信メッセージを評価するための選択式を入力します。

  6. [レスポンスの作成] を選択します。

  7. マッピングテンプレートを定義して、返されるメッセージペイロードの変換を設定することもできます。[テンプレートを作成] をクリックします。

  8. キー名を入力します。デフォルトのテンプレート選択式を選択する場合は、\$default を入力します。

  9. [レスポンステンプレート] に、コードエディタのマッピングテンプレートを入力します。

  10. [テンプレートを作成] をクリックします。

  11. [API をデプロイ] を選択して、API をデプロイします。

以下の wscat コマンドを使用して、API に接続します。wscat の詳細については、「wscat を使用した WebSocket API への接続とメッセージの送信」を参照してください。

wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test

ルートを呼び出すと、返されたメッセージペイロードが戻るはずです。

AWS CLI を使用して統合レスポンスを設定する

AWS CLI を使用して WebSocket API の統合レスポンスを設定するには、create-integration-response コマンドを呼び出します。以下の CLI コマンドは、$default 統合レスポンスを作成する例を示しています。

aws apigatewayv2 create-integration-response \
    --api-id vaz7da96z6 \
    --integration-id a1b2c3 \
    --integration-response-key '$default'