AWS AppSync Merged API でマイクロサービスの GraphQL を統合 - チーム分散開発の実践
複数チームが独立して開発 / デプロイする GraphQL API を単一エンドポイントに統合する方法を解説します。スキーマ競合の回避策と認証戦略の設計も紹介します。
Merged API の必要性
マイクロサービスアーキテクチャで複数チームが GraphQL API を開発する場合、フロントエンドは複数のエンドポイントにリクエストを送る必要があり、クライアント側の複雑さが増します。Merged API はこの問題を解決し、複数のソース API を単一のエンドポイントに統合します。ユーザーチームの User API、注文チームの Order API、商品チームの Product API をそれぞれ独立して開発 / デプロイしつつ、フロントエンドからは 1 つの GraphQL エンドポイントでアクセスできます。API Gateway のような REST ベースの API 集約と異なり、GraphQL のスキーマレベルで統合されるため、クロスサービスのクエリも単一のリクエストで実行できます。
ソース API の設計と独立デプロイ
各チームはソース API として独立した AppSync API を開発します。スキーマ、リゾルバー、データソースはソース API ごとに管理され、チームは自分の API を自由にデプロイ / 更新できます。ソース API の更新は自動的に Merged API に反映されます。スキーマの競合 (同名の Query フィールド、同名の型定義) はマージ時に検出され、エラーとして報告されます。競合を避けるため、チーム間でスキーマの命名規則を事前に合意し、名前空間的なプレフィックス (user_、order_) を使用するか、共通の型定義を共有スキーマとして管理する設計が推奨されます。
認証戦略
Merged API レベルでデフォルトの認証方式 (Cognito ユーザープール、 IAM 、 API キー、 Lambda オーソライザー) を設定します。ソース API ごとに追加の認証方式を設定でき、特定のフィールドに対してソース API の認証を適用できます。例えば、 Merged API のデフォルト認証を Cognito に設定しつつ、管理者向けの Mutation にはソース API レベルで IAM 認証を追加する構成が可能です。@aws_auth ディレクティブでフィールドレベルの認証を制御し、特定のフィールドを特定の Cognito グループのみに公開できます。
Merged API の料金と制約
Merged API の料金は通常の AppSync API と同じで、クエリ / ミューテーションは 100 万リクエストあたり約 4.00 ドルです (2026 年 8 月時点)。Merged API 自体に追加料金は発生しませんが、ソース API の数に上限 (デフォルト 10) があり、大規模なマイクロサービス環境では上限緩和の申請が必要です。ソース API のリゾルバーが Lambda を呼び出す場合、Lambda の料金はソース API のアカウントに課金されます。Merged API のキャッシュを有効にすると、ソース API をまたいだクエリ結果がキャッシュされ、バックエンドの呼び出し回数を削減できます。
リアルタイム更新とサブスクリプション
GraphQL の強みの一つは、サブスクリプションによるリアルタイムなデータ更新です。Merged API でも、各ソース API が定義したサブスクリプションを統合し、フロントエンドは単一のエンドポイントを通じて複数サービスの更新通知を購読できます。WebSocket 経由でサーバーから変更が push されるため、チャットや通知、ダッシュボードのライブ更新といった用途に活用できます。チームごとに独立して定義したリアルタイム機能を、クライアントから一貫した形で扱えるため、分散開発とリッチな体験を両立できます。
監視とオブザーバビリティ
統合された API は、どのソース API のどのリゾルバーが遅いのかを見極めることが運用の鍵になります。CloudWatch のログでリクエストやリゾルバーの実行状況を記録し、X-Ray の分散トレースでリクエストがソース API やバックエンドをどう経由したかを可視化します。これにより、レイテンシのボトルネックやエラーの発生箇所を特定できます。フィールド単位の解決状況を追えるようにしておくと、特定のクエリが重い原因を切り分けやすくなります。複数チームのコードが関わるからこそ、横断的に観測できる仕組みを整えておくことが重要です。
CI/CD とスキーマ管理
各チームが独立してデプロイする以上、スキーマの整合性を保つ仕組みが欠かせません。ソース API の変更は CI/CD パイプラインに組み込み、マージ時のスキーマ競合を自動で検知して、破壊的変更が本番へ流れないようにします。命名規則やプレフィックスをチーム間で合意し、共有する型は共通定義として管理します。クライアントが依存するフィールドを壊さないよう、契約テストを通してから反映する運用にすると、分散開発でも安定したエンドポイントを維持できます。スキーマをコードとして版管理することが、変更の追跡と安全な進化を支えます。
キャッシュとパフォーマンス最適化
複数のソース API をまたぐクエリは、バックエンドへの呼び出しが増えがちです。Merged API のキャッシュを有効にすると、頻繁に同じ結果を返すクエリの応答を一定時間保持し、バックエンドの負荷とレイテンシを抑えられます。リゾルバーの設計では、関連データを 1 件ずつ取得して呼び出しが膨らむ N+1 問題に注意し、まとめて取得するバッチ処理で効率化します。各ソース API が自分の責務範囲で効率的にデータを返すよう設計し、統合層で過剰な再取得が起きないようにすることで、全体のパフォーマンスを保てます。
まとめ
AppSync Merged API は複数チームの GraphQL API を単一エンドポイントに統合するサービスです。各チームの独立したデプロイを維持しつつ、フロントエンドにはシンプルな単一エンドポイントを提供します。マイクロサービスアーキテクチャで GraphQL を採用する場合の標準的なパターンです。
参考資料 (AWS 公式)
本ページの一次情報は AWS 公式サイトと公式ドキュメントです。最新の仕様と料金は次の公式ページで確認できます。
本ページと公式ドキュメントの記述が食い違う場合は、公式ドキュメントを正としてください。