GraphQL Subscription

GraphQL Subscription とは

GraphQL Subscription は、GraphQL の 3 つの操作タイプ (Query, Mutation, Subscription) の 1 つで、サーバーからクライアントへリアルタイムにデータ更新を配信する仕組みである。WebSocket 上で動作し、チャット、通知、ダッシュボードのリアルタイム更新に使われる。

基本的な使い方

基本的な使い方の例を示す。

# スキーマ定義
type Subscription {
  orderStatusChanged(orderId: ID!): Order!
  newMessage(channelId: ID!): Message!
}

# クライアントからのサブスクリプション
subscription OnOrderStatusChanged($orderId: ID!) {
  orderStatusChanged(orderId: $orderId) {
    id
    status
    updatedAt
  }
}

Query / Mutation との違い

Query / Mutation との違いを以下にまとめる。

操作	方向	プロトコル	用途
Query	クライアント → サーバー	HTTP	データの取得
Mutation	クライアント → サーバー	HTTP	データの変更
Subscription	サーバー → クライアント	WebSocket	リアルタイム更新

AWS AppSync での実装

AppSync は GraphQL Subscription をマネージドでサポートする。WebSocket の接続管理が不要で、Mutation をトリガーに自動的にサブスクライバーに配信する。

# AppSync: Mutation が実行されると、自動的に Subscription に配信
type Mutation {
  updateOrderStatus(orderId: ID!, status: String!): Order!
}

type Subscription {
  onUpdateOrderStatus(orderId: ID!): Order
    @aws_subscribe(mutations: ["updateOrderStatus"])
}

クライアントが onUpdateOrderStatus をサブスクライブしている状態で、別のクライアントが updateOrderStatus Mutation を実行すると、サブスクライバーに自動的に更新が配信される。

SSE / WebSocket API との使い分け

SSE / WebSocket API との使い分けを以下に整理する。

手法	用途	GraphQL 統合
GraphQL Subscription	GraphQL API のリアルタイム拡張	ネイティブ
WebSocket API (API Gateway)	カスタムプロトコル、チャット	手動実装
SSE	一方向のプッシュ通知	手動実装

GraphQL を既に使っているプロジェクトでは、Subscription が最も自然な選択だ。

スケーリングの課題

Subscription は WebSocket の永続接続を維持するため、接続数に応じてサーバーリソースが必要になる。AppSync はマネージドで接続管理を行うため、スケーリングの心配が不要だ。

GraphQL Subscription の関連書籍も参考になる。