次の方法で共有


Azure API Management での GraphQL API の概要

適用対象: すべての 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 に対してテスト クエリを実行します。

次の手順