# API Gateway での WebSocket API の概要
<a name="apigateway-websocket-api-overview"></a>

API Gateway では、AWS のサービス (Lambda や DynamoDB など) または HTTP エンドポイントのステートフルフロントエンドとして WebSocket API を作成できます。WebSocket API は、クライアントアプリから受信するメッセージのコンテンツに基づいて、バックエンドを呼び出します。

WebSocket API は、リクエストを受け取って応答する REST API とは異なり、クライアントアプリとバックエンド間の双方向通信をサポートします。バックエンドは、接続されたクライアントにコールバックメッセージを送信できます。

WebSocket API では、受信する JSON メッセージは設定したルートに基づいてバックエンド統合に転送されます (JSON 以外のメッセージは、設定した `$default` ルートに転送されます)。

*ルート*には*ルートキー*が含まれます。これは、*ルート選択式*が評価されたときに予期される値です。属性 `routeSelectionExpression` は、API レベルで定義されます。メッセージペイロードに存在することが予期される JSON プロパティを指定します。ルート選択式の詳細については、「[ルート選択式](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions)」を参照してください。

たとえば、JSON メッセージに `action` プロパティが含まれていて、このプロパティに基づいてさまざまなアクションを実行する場合、ルート選択式は `${request.body.action}` のようになります。ルーティングテーブルでは、このテーブルで定義したカスタムルートキーの値に対して、`action` プロパティの値を一致させることによって、実行するアクションを指定します。

## WebSocket API のルートを使用する
<a name="apigateway-websocket-api-overview-routes"></a>

3 つの事前定義されたルート (`$connect`、`$disconnect`、および `$default`) を使用できます。さらに、カスタムルートを作成することができます。
+ API Gateway は、クライアントと WebSocket API 間の永続的な接続が開始されたときに、`$connect` ルートを呼び出します。
+ API Gateway は、クライアントまたはサーバーが API から切断したときに、`$disconnect` ルートを呼び出します。
+ API Gateway は、一致するルートが見つかった場合、メッセージに対してルート選択式が評価された後でカスタムルートを呼び出します。この一致により、呼び出される統合が決まります。
+ ルート選択式をメッセージに対して評価できない場合や、一致するルートが見つからない場合、API Gateway は `$default` ルートを呼び出します。

`$connect` および `$disconnect` ルートの詳細については、「[接続されたユーザーとクライアントアプリを管理する: `$connect` ルートおよび `$disconnect` ルート](apigateway-websocket-api-route-keys-connect-disconnect.md)」を参照してください。

`$default` ルートおよびカスタムルートの詳細については、「[API Gateway の `$default` ルートおよびカスタムルートを使用してバックエンド統合を呼び出す](apigateway-websocket-api-routes-integrations.md)」を参照してください。

## 接続されたクライアントアプリケーションにデータを送信する
<a name="apigateway-websocket-api-overview-send-data"></a>

バックエンドサービスは、接続されたクライアントアプリにデータを送信できます。以下を実行することにより、データを送信できます。
+ 統合を使用してレスポンスを送信します。レスポンスは、定義したルートレスポンスでクライアントに返されます。
+ `@connections` API を使用して POST リクエストを送信することができます。詳細については、「[バックエンドサービスでの `@connections` コマンドの使用](apigateway-how-to-call-websocket-api-connections.md)」を参照してください。

## WebSocket API ステータスコード
<a name="apigateway-websocket-status-codes"></a>

API Gateway WebSocket API は、[WebSocket Close Code Number Registry](https://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number) に説明されているように、サーバーからクライアントへの通信に次のステータスコードを使用します。

1001  
API Gateway は、クライアントが 10 分間アイドル状態であるか、最大 2 時間の接続の存続時間に達したときに、このステータスコードを返します。

1003  
API Gateway は、エンドポイントがバイナリメディアタイプを受信すると、このステータスコードを返します。バイナリメディアタイプは WebSocket API ではサポートされていません。

1005  
API Gateway は、クライアントがクローズコードなしでクローズフレームを送信すると、このステータスコードを返します。

1006  
API Gateway は、WebSocket クローズフレームなしで TCP 接続が閉じられるなど、接続が予期せず閉じられた場合、このステータスコードを返します。

1008  
API Gateway は、エンドポイントが特定のクライアントから受信したリクエストが多すぎると、このステータスコードを返します。

1009  
API Gateway は、エンドポイントが処理するには大きすぎるメッセージを受信すると、このステータスコードを返します。

1011  
API Gateway は、内部サーバーエラーが発生したときに、このステータスコードを返します。

1012  
サービスが再起動すると、API Gateway はこのステータスコードを返します。