GraphQL API フレームワークを使用したレコードデータのクエリ
コンポーネントまたはサードパーティシステムからレコードデータをクエリするカスタム GraphQL API を作成します。
たとえば、SLA に関連付けられたケースを表示するコンポーネントを作成できます。Next Experience UI フレームワーク を使用して必要なコンポーネントを開発し、 ケーステーブルのデータを定義する GraphQL スキーマを作成することで、 プラットフォームからケースデータにアクセスできます。
コンポーネントの開発の詳細については、「 Workspace のコンポーネントの開発」を参照してください。
GraphQL のメリット
GraphQL は、クライアント側の開発用に最適化された Web クエリ言語です。スクリプト化された GraphQL を使用すると、次のことができます。
- イントロスペクションを通じてクエリ可能なフィールドとオブジェクトを検出します。
- コンポーネントから必要なデータを正確にクエリします。
- REST 要求の複数のエンドポイントとは対照的に、単一の API から複数のクエリを管理します。
- スキーマを公開してサードパーティシステムと統合します。
- コンポーネントから GraphQL クエリを生成し、応答を処理します。
使用前の注意事項
カスタム GraphQL API の作成を開始する前に、次のことを確認します。
- スキーマを作成するための GraphQL の知識
- API の動作を定義するための JavaScript の知識
- Web コンポーネントの概念に関する一般的な知識
- レコードデータを使用するカスタムワークスペースコンポーネント
- スキーマで公開する ServiceNow データモデルの理解
- リゾルバースクリプトでフィールドをレコードデータにマッピングするための GlideRecord の知識
GraphQL の概要
スクリプト化された GraphQL API の作成には、次の部分が含まれます。
- GraphQL スキーマ定義言語 (SDL)
- GraphQL クエリで利用可能なフィールドの構造とデータタイプを定義します。GraphQL スクリプト化済みスキーマ [sys_graphql_schema] テーブルの [スキーマ] スクリプトフィールドを使用して、SDL を定義できます。SDL はクエリ操作と変更操作のみをサポートしています。
- リゾルバー
- 各フィールドによって返されるデータを定義します。[GraphQL スクリプト化済みスキーマ] フォームで [GraphQL スクリプト化リゾルバー] 関連リストの各フィールドのリゾルバーを定義できます。
- タイプリゾルバー
- インターフェイスとユニオンを GraphQL の具象タイプに転換させます。たとえば、ユニオンを
incidentタイプかproblemタイプに定義します。タイプリゾルバースクリプトを使用して、いつどちらを返すかを定義します。[GraphQL スクリプト化済みスキーマ] フォームで [GraphQL スクリプト化済みタイプリゾルバー (GraphQL Scripted Typeresolvers)] 関連リストのタイプリゾルバーを定義できます。 - リゾルバーマッピング
- リゾルバーをスキーマのフィールドにマッピングします。[GraphQL スクリプト化済みスキーマ] フォームで [GraphQL スクリプト化済みリゾルバーマッピング (GraphQL Scripted Resolver Mappings)] 関連リストのリゾルバーマッピングを定義できます。
GraphQL クエリ言語の詳細については、GraphQL の Web サイトを参照してください。
GraphQL API へのクエリをテストするには、統合された GraphQL テストツールである GraphQL エクスプローラーを使用できます。詳細については、「GraphQL Explorer で GraphQL API をテストする」を参照してください。
制限事項
次の GraphQL 機能はサポートされていません。
- サブスクリプションの操作
- カスタムスカラータイプ
イントロスペクション
デフォルトでは、カスタムスキーマへのイントロスペクションクエリは有効になっていません。イントロスペクションをオンにする場合は「GraphQL スキーマのイントロスペクションクエリの有効化」を参照してください。
名前空間
GraphQL API には 2 つの異なる名前空間があります。
- アプリケーション名前空間
- カスタムアプリケーションの名前空間。アプリケーション名前空間の詳細については、「 アプリケーションスコープ」を参照してください。
- スキーマ名前空間
- すべてのクエリが一意になるようにするスキーマの名前空間。1 つのアプリケーションに複数のスキーマ名前空間を含めることができます。
データをクエリするときは、クエリに両方の名前空間を含める必要があります。たとえば、次のクエリは次の名前空間でデータを検索します。
- アプリケーション名前空間：
x_graph_scope - スキーマ名前空間：
planet
query {
x_graph_scope {
planet {
findAll {
name
mass
distance
}
}
}
}ディレクティブとグローバル関数
@sourceスキーマディレクティブGraphQL フィールドを親オブジェクトのプロパティの値にマッピングします。フィールドに個別のリゾルバースクリプトがある場合、システムは親オブジェクトの代わりに解決されるレコードを使用します。
スキーマスクリプトで
@sourceディレクティブを使用します。@deferクエリディレクティブ- クエリの後半まで GraphQL フラグメントの処理を保留します。このクエリディレクティブを使用して、フラグメント内の応答の遅いフィールドのデータの戻しを遅らせます。保留されたフラグメントのフィールド結果をマルチパート応答としてストリーミングします。注:
@deferディレクティブを使用するには、GraphQL クライアントがマルチパート/混在 HTTP ヘッダーを受け入れる必要があります。たとえば、HTTP ヘッダーをAccept: multipart/mixed; boundary="-"に設定します。@deferディレクティブを使用して、ユーザーのインタラクションまでの時間を短縮します。 パフォーマンスが低下する可能性があるため、このクエリディレクティブを無差別に適用しないでください。パフォーマンステストを実施して、パフォーマンスを向上させるためにどのフィールドを保留できるかを判断してください。 - リゾルバー関数
これらの関数はグローバル env オブジェクトで使用できます。
- getArguments()：前のフィールドの引数を返します。
- getSource()：親オブジェクトを返します。
リゾルバースクリプトで使用します。
- タイプリゾルバー関数
これらの関数はグローバル env オブジェクトで使用できます。
- getArguments()：前のフィールドの引数を返します。
- getObject()：親オブジェクトを返します。
- getTypeName()：インターフェイスまたは共用タイプの名前を返します。
タイプリゾルバースクリプトで使用します。
デモアプリケーション
変更とクエリを含むデモの GraphQL PTO カレンダースキーマを表示するには、GraphQL Framework Demo Application プラグイン (com.glide.graphql.framework.demo) を有効にします。