Amazon API Gateway WebSocket APIs

解決する課題

• チャットや通知で双方向のリアルタイム通信がしたい
• WebSocketサーバーを自前で常駐運用したくない
• 多数の同時接続を接続管理ごとマネージドに任せたい

主要概念と用語

• 接続（コネクション）: クライアントが繋ぎっぱなしにする経路。各接続に一意の接続IDが付く
• ルート: 受信メッセージの内容で処理先を振り分ける仕組み
• $connect / $disconnect: 接続開始・切断時に呼ばれる組み込みルート
• $default: どのルートにも一致しないメッセージを受けるルート
• ルート選択式: メッセージのどのフィールドでルートを選ぶかを定義する式
• @connections Management API: サーバー側から接続IDを指定してメッセージを送る逆方向API

仕様・制限・クォータ

• フルマネージドで接続を維持し、自動スケールする
• 接続はアイドル 10 分、継続 2 時間で終了する。どちらも引き上げ不可
• 統合タイムアウトは 50 ミリ秒〜29 秒。新規接続は既定で毎秒 500 件
• メッセージは 128 KB、フレームは 32 KB が上限。大きいデータは S3 参照にする

内部の仕組み

横にスクロール

クライアントが接続すると $connect ルートが呼ばれ、ここでだけ Lambda オーソライザーを使えます。接続統合が完了するまで接続は保留され、失敗すると確立されません。 以降クライアントが送るメッセージはルート選択式で評価され、一致したルート（無ければ $default）の統合先（Lambda等）へ振り分けられます。 切断時には $disconnect ルートが呼ばれますが、切断済みの接続に対するベストエフォート通知なので、これだけに後処理を依存させません。

サーバー側からクライアントへ送るのは逆方向で、@connections の Management API に接続IDを指定して POST します。 そのため「誰がどの接続IDか」をDynamoDB等に保存しておくのが基本パターンです。 再接続をまたぐ順序や一度だけの配送は保証されません。メッセージIDと連番を付け、受信側で重複排除と欠番検知を行います。

設計パターン / ベストプラクティス

• WebSocket API + Lambda + DynamoDB: 接続をDynamoDBに記録し、送信時に引き当てる
• $connect でオーソライザー（Lambda/IAM）を使い接続時に認証する
• ファンアウトしたい時は保存済みの接続IDを走査して順に送信する
• 大きいペイロードはS3に置きメッセージには参照を載せる
• クライアントに再接続とバックオフを実装する

運用・監視

• メトリクス: ConnectCount MessageCount IntegrationError ClientError ExecutionError
• アクセスログ/実行ログをCloudWatchへ出して接続・切断・ルート選択を追跡
• 410 Gone が返る送信は切断済みの接続ID。DynamoDB側から削除する
• スロットリングはステージ/ルート単位で設定できる

コスト

• メッセージ数と接続時間（接続分）で課金される従量制
• 常駐サーバーが不要なため、接続が疎な用途ではコスト効率が良い
• 切断済みの接続IDを掃除し、無駄な送信試行を減らすと運用コストも下がる

セキュリティ

• $connect 時にLambdaオーソライザー / IAM認証で接続を認証する
• 接続後のメッセージにはトークン検証などアプリ側の認可も検討する
• 通信は TLS（wss）。ルートのスロットリングと入力検証で濫用を抑える
• IAMで @connections Management API の呼び出し権限を最小化する

関連サービス・比較

同じ API Gateway のプロトコルである REST API（リクエスト/レスポンス型）と、通信モデルが根本的に異なります。

ハンズオン / CLI例

# WebSocket API を作成（ルート選択式を指定）
aws apigatewayv2 create-api \
  --name chat-ws --protocol-type WEBSOCKET \
  --route-selection-expression '$request.body.action'

# サーバー側から接続IDを指定してメッセージを送る（逆方向）
aws apigatewaymanagementapi post-to-connection \
  --connection-id "$CONN_ID" \
  --endpoint-url "https://abcde12345.execute-api.ap-northeast-1.amazonaws.com/prod" \
  --data '{"message":"hello"}'