API Gateway の $default ルートおよびカスタムルートを使用してバックエンド統合を呼び出す
次のセクションでは、WebSocket API の $default ルートまたはカスタムルートを使用してバックエンド統合を呼び出す方法について説明します。
トピック
ルートを使用したメッセージの処理
API Gateway WebSocket API では、クライアントからバックエンドサービスに、またはその逆にメッセージを送信できます。HTTP のリクエスト/レスポンスモデルとは異なり、WebSocket ではクライアントがアクションを実行することなく、バックエンドがクライアントにメッセージを送信できます。
メッセージの形式は JSON または JSON 以外とすることができます。ただし、メッセージの内容によっては、JSON メッセージのみを特定の統合にルーティングできます。JSON 以外のメッセージは、$default ルートによってバックエンドにパススルーされます。
注記
API Gateway は最大 128 KB までのメッセージペイロードをサポートし、最大フレームサイズは 32 KB です。メッセージが 32 KB を超えた場合は、それぞれが 32 KB 以下の複数のフレームに分割する必要があります。大きなメッセージ (またはフレーム) が受信された場合、接続は 1009 コードで閉じられます。
現時点では、バイナリペイロードはサポートされていません。バイナリフレームが受信された場合、接続は 1003 コードで閉じられます。ただし、バイナリペイロードはテキストに変換できます。「API Gateway での WebSocket API のバイナリメディアタイプ」を参照してください。
API Gateway の WebSocket API では、メッセージの内容に基づいて JSON メッセージをルーティングし、特定のバックエンドサービスを実行できます。クライアントが WebSocket 接続経由でメッセージを送信すると、これが WebSocket API に対するルートリクエストになります。リクエストが、API Gateway の対応するルートキーを持つルートと照合されます。WebSocket API のルートリクエストは、API Gateway コンソールで、または AWS CLI もしくは AWS SDK を使用してセットアップできます。
注記
AWS CLI および AWS SDK で、統合を作成する前または後にルートを作成できます。現在のところ、コンソールは統合の再利用をサポートしていないため、最初にルートを作成してから、そのルートの統合を作成する必要があります。
統合リクエストを進める前にルートリクエストの検証を実行するよう API Gateway を設定できます。検証に失敗すると、API Gateway はバックエンドを呼び出さずにリクエストを失敗させ、次のような "Bad request body" ゲートウェイレスポンスをクライアントに送信し、CloudWatch Logs で検証の失敗を発行します。
{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}
これによりバックエンドへの不要な呼び出しが減り、API のその他の要件に集中することができます。
また、API のルートに対するルートのレスポンスを定義し、双方向通信を有効にすることもできます。ルートレスポンスは、特定のルートの統合の完了時にどのようなデータがクライアントに送信されるかを示します。たとえば、クライアントがレスポンスを受信せずにバックエンドにレスポンスを送信するようにする場合 (単方向通信)、ルートのレスポンスを定義する必要はありません。ただし、ルートレスポンスのルートを提供しない場合、API Gateway は統合の結果に関する情報をクライアントに送信しません。
$default ルート
すべての API Gateway WebSocket API は、$default ルートを持つことができます。これは、次の方法で使用できる特殊なルーティング値です。
-
これを定義されたルートキーと一緒に使用し、定義されたいずれのキーとも一致しない受信メッセージの「フォールバック」ルート (たとえば、特定のエラーメッセージを返す汎用モック統合) を指定できます。
-
定義されたルートキーなしでこれを使用し、バックエンドコンポーネントにルーティングを委任するプロキシモデルを指定できます。
-
これを使用して、JSON 以外のペイロードのルートを指定できます。
カスタムルート
メッセージの内容に基づいて特定の統合を呼び出す場合、カスタムルートを作成してこれを行うことができます。
カスタムルートは、指定されたルートキーと統合を使用します。受信メッセージにプロパティ JSON プロパティが含まれていて、そのプロパティがルートキーの値に一致する値に評価される場合、API Gateway は統合を呼び出します。(詳しくは、API Gateway での WebSocket API の概要 を参照してください)。
たとえば、チャットルームアプリケーションを作成するとします。ルート選択式が $request.body.action である WebSocket API を作成して開始できます。次に、joinroom および sendmessage の 2 つのルートを定義できます。クライアントアプリは、次のようなメッセージを送信して joinroom ルートを呼び出す場合があります。
{"action":"joinroom","roomname":"developers"}
また、次のようなメッセージを送信して sendmessage ルートを呼び出す場合があります。
{"action":"sendmessage","message":"Hello everyone"}
API Gateway WebSocket API 統合を使用したビジネスロジックへの接続
API Gateway WebSocket API のルートを設定したら、使用する統合を指定する必要があります。ルートリクエストとルートレスポンスを持つことができるルートと同じように、統合は統合リクエストと統合レスポンスを持つことができます。統合リクエストには、クライアントから受け取ったリクエストを処理するためにバックエンドで予期される情報が含まれます。統合レスポンスには、バックエンドが API Gateway に返すデータが含まれます。このデータは、クライアントに送信するメッセージを作成するために使用される場合があります (ルートレスポンスが定義されている場合)。
統合の設定の詳細については、「API Gateway での WebSocket API の統合」を参照してください。
WebSocket API と REST API の重要な相違点
WebSocket API の統合は REST API の統合に似ていますが、次のような違いがあります。
-
現時点では、API Gateway コンソールで最初にルートを作成してから、そのルートのターゲットとして統合を作成する必要があります。ただし、API と CLI では、ルートと統合を任意の順序で個別に作成できます。
-
複数のルートに単一の統合を使用できます。たとえば、相互に密接に関連した一連のアクションがある場合は、それらのすべてのルートを単一の Lambda 関数に移動したい場合があります。統合の詳細を複数回定義する代わりに、1 回指定して、関連する各ルートに割り当てることができます。
注記
現在のところ、コンソールは統合の再利用をサポートしていないため、最初にルートを作成してから、そのルートの統合を作成する必要があります。
AWS CLI、AWS SDK では、ルートのターゲットを
"integrations/の値に設定して統合を再利用できます。ここで{integration-id}"{integration-id}" -
API Gateway は、ルートと統合で使用できる複数の選択式を提供します。入力テンプレートまたは出力マッピングを選択するために、コンテンツタイプに依存する必要はありません。ルート選択式の場合と同様に、API Gateway で評価される選択式を定義して、適切な項目を選択できます。それらのすべては、一致するテンプレートが見つからない場合に、
$defaultテンプレートにフォールバックされます。-
統合リクエストで、テンプレート選択式は
$request.body.および静的な値をサポートしています。<json_path_expression> -
統合レスポンスで、テンプレート選択式は
$request.body.、<json_path_expression>$integration.response.statuscode、$integration.response.header.、および静的な値をサポートします。<headerName>
-
リクエストとレスポンスが同期的に送信される HTTP プロトコルでは、通信は基本的に一方向です。WebSocket プロトコルでは、通信は双方向です。レスポンスは非同期であり、必ずしもクライアントのメッセージの送信と同じ順序でクライアントによって受信される必要はありません。さらに、バックエンドはクライアントにメッセージを送信できます。
注記
AWS_PROXY または LAMBDA_PROXY 統合を使用するように設定されたルートでは、通信は一方向で、API Gateway は自動的にルートレスポンスにバックエンドレスポンスをパススルーしません。たとえば、LAMBDA_PROXY 統合の場合は、 Lambda 関数が返す本文はクライアントに返されません。クライアントが統合レスポンスを受信するには、ルートレスポンスを定義して、双方向通信を可能にする必要があります。
