Azure API Management での GraphQL API の概要

[アーティクル]
05/05/2024

適用対象: すべての API Management レベル

API Management を使用して、GraphQL API ( GraphQL クエリ言語に基づく API) を管理できます。 GraphQL では、API 内のデータの完全で理解しやすい説明が提供され、それによりクライアントではまさに必要とするデータを効率的に取得できます。 GraphQL の詳細についてはこちらを参照してください

API Management は、GraphQL API のインポート、管理、保護、テスト、発行、監視に役立ちます。次の 2 つの API モデルのいずれかを選択できます。

パススルー GraphQL	合成 GraphQL
▪️ 既存の GraphQL サービスエンドポイントへのパススルー API ▪️ GraphQL のクエリ、ミューテーション、サブスクリプションのサポート	▪️ カスタム GraphQL スキーマに基づく API ▪️ GraphQL のクエリ、ミューテーション、サブスクリプションのサポート ▪️ (HTTP データソースなどへの) カスタムリゾルバーを構成する ▪️ レガシ API からのデータを使用しながら、GraphQL スキーマと GraphQL ベースのクライアントを開発する

可用性

GraphQL API は、API Management のすべてのサービスレベルでサポートされています
合成 GraphQL API は現在、API Management ワークスペースではサポートされていません
合成 GraphQL API での GraphQL サブスクリプションのサポートは現在プレビュー段階であり、従量課金レベルでは使用できません

GraphQL とは

GraphQL は、API 用のオープンソースの業界標準クエリ言語です。リソースに対するアクションを中心に設計された REST スタイルの API とは異なり、GraphQL API では、より広範なユースケースがサポートされ、データ型、スキーマ、クエリに重点が置かれています。

GraphQL 仕様では、REST API に依存するクライアント Web アプリで発生する一般的な問題を明示的に解決します。

1 つのページのデータニーズを満たすために大量の要求が必要になる場合があります
REST API では、多くの場合、レンダリングされるページで必要とされるより多くのデータが返されます
クライアントアプリでは、新しい情報を取得するためにポーリングする必要があります

GraphQL API を使用すると、クライアントアプリは、GraphQL サービスに単一要求として送信されるクエリドキュメントに、ページをレンダリングするために必要なデータを指定できます。また、クライアントアプリでは、GraphQL サービスからリアルタイムでプッシュされるデータ更新をサブスクライブすることもできます。

スキーマと型や種類

API Management で、バックエンドの GraphQL API エンドポイントから取得したか、ユーザー自身がアップロードした GraphQL API を GraphQL スキーマから追加します。 GraphQL スキーマには、次のことが記述されています。

クライアントが GraphQL API から要求できるデータのオブジェクト型とフィールド
クエリなど、データに対して許可される操作の種類
共用体やインターフェイスなどの、データの柔軟性と制御を強化するその他の型

たとえば、ユーザーデータの基本的な GraphQL スキーマと、すべてのユーザーのクエリは次のようになります。

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

操作の種類

API Management では、GraphQL スキーマで次の操作の種類がサポートされています。これらの操作の種類の詳細については、GraphQL の仕様に関するページを参照してください。

クエリ - REST の GET 操作と同様に、データをフェッチします
ミューテーション - REST の PUT または PATCH 操作と同様に、サーバー側のデータを変更します
サブスクリプション - これを使用すると、GraphQL サービスでのデータの変更について、サブスクライブしているクライアントにリアルタイムで通知できます

たとえば、GraphQL ミューテーションによってデータが変更されると、サブスクライブしているクライアントは、その変更に関する通知を自動的に受け取ることができます。

重要

API Management では、graphql-ws WebSocket プロトコルを使用して実装されたサブスクリプションがサポートされます。クエリとミューテーションは、WebSocket ではサポートされていません。

その他の型

API Management は、GraphQL スキーマで共用体型とインターフェイス型をサポートします。

リゾルバー

"リゾルバー" は GraphQL スキーマからバックエンドデータへのマッピングを行い、オブジェクト型の各フィールドのデータを生成します。データソースには、API、データベース、または別のサービスを指定できます。たとえば、リゾルバー関数は、前の例の users クエリのデータを返す役割を担います。

API Management では、オブジェクト型のフィールドをバックエンドデータソースにマップするリゾルバーを作成できます。合成 GraphQL API スキーマのフィールド用にリゾルバーを構成しますが、パススルー GraphQL API で使用される既定のフィールドリゾルバーをオーバーライドするようにリゾルバーを構成することもできます。

API Management は現在、HTTP API、Cosmos DB、Azure SQL データソースに基づくリゾルバーをサポートし、GraphQL スキーマ内のフィールドのデータを返します。各リゾルバーは、調整されたポリシーを使用してデータソースに接続し、データを取得するように構成されます。

データソース	リゾルバーポリシー
HTTP ベースのデータソース (REST または SOAP API)	http-data-source
Cosmos DB データベース	cosmosdb-data-source
Azure SQL データベース	sql-data-source

たとえば、上記の users クエリの HTTP API ベースリゾルバーは、バックエンド REST API の GET 操作にマップされる場合があります。

<http-data-source>
	<http-request>
		<set-method>GET</set-method>
		<set-url>https://myapi.contoso.com/api/users</set-url>
	</http-request>
</http-data-source>

リゾルバーの設定の詳細については、「GraphQL リゾルバーを構成する」を参照してください。

GraphQL API を管理する

GraphQL 固有の攻撃をセキュリティで保護するために、既存のアクセス制御ポリシーと GraphQL 検証ポリシーの両方を適用することで、GraphQL API をセキュリティで保護します。
GraphQL スキーマを調べ、Azure と開発者ポータルで GraphQL API に対してテストクエリを実行します。

次の方法で共有