Amazon API Gateway WebSocket APIs

解決する課題

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

主要概念と用語

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

仕様・制限・クォータ

• フルマネージドで接続を維持し、自動スケールする
• 接続のアイドルタイムアウトや、最大接続継続時間に上限がある
• 一定時間メッセージが無いとアイドルとして切断され得る
• メッセージのペイロードサイズに上限がある（大きいデータはS3＋参照が定石）

内部の仕組み

クライアントが接続すると $connect ルートが呼ばれ、ここで認証や接続IDの保存を行います。 以降クライアントが送るメッセージはルート選択式で評価され、一致したルート（無ければ $default）の統合先（Lambda等）へ振り分けられます。 切断時には $disconnect ルートが呼ばれます。

サーバー側からクライアントへ送るのは逆方向で、@connections の Management API に接続IDを指定して POST します。 そのため「誰がどの接続IDか」をDynamoDB等に保存しておくのが基本パターンです。

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

• 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）。前段にWAFを併用して保護できる
• 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"}'