バックエンド統合の呼び出し: $default ルートおよびカスタムルート

ルートを使用したメッセージの処理

API Gateway WebSocket API では、クライアントからバックエンドサービスに、またはその逆にメッセージを送信できます。HTTP のリクエスト/レスポンスモデルとは異なり、WebSocket ではクライアントがアクションを実行することなく、バックエンドがクライアントにメッセージを送信できます。

メッセージの形式は JSON または JSON 以外とすることができます。ただし、メッセージの内容によっては、JSON メッセージのみを特定の統合にルーティングできます。JSON 以外のメッセージは、$default ルートによってバックエンドにパススルーされます。

API Gateway の WebSocket API では、メッセージの内容に基づいて JSON メッセージをルーティングし、特定のバックエンドサービスを実行できます。クライアントが WebSocket 接続経由でメッセージを送信すると、これが WebSocket API に対するルートリクエストになります。リクエストが、API Gateway の対応するルートキーを持つルートと照合されます。WebSocket API のルートリクエストは、API Gateway コンソールで、または 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 プロパティが含まれていて、そのプロパティがルートキーの値に一致する値に評価される場合、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 に返すデータが含まれます。このデータは、クライアントに送信するメッセージを作成するために使用される場合があります (ルートレスポンスが定義されている場合)。

統合の設定の詳細については、「WebSocket API 統合の設定」を参照してください。

WebSocket API と REST API の重要な相違点

WebSocket API の統合は REST API の統合に似ていますが、次のような違いがあります。

リクエストとレスポンスが同期的に送信される HTTP プロトコルでは、通信は基本的に一方向です。WebSocket プロトコルでは、通信は双方向です。レスポンスは非同期であり、必ずしもクライアントのメッセージの送信と同じ順序でクライアントによって受信される必要はありません。さらに、バックエンドはクライアントにメッセージを送信できます。