GraphQL を使用したイントロスペクション

GraphQL は、タイプ・システムに基づく照会言語です。 GraphQL タイプは、サポートされるオブジェクト、オブジェクトに関連付けられるフィールド、照会できる内容、および照会方法を定義します。これらはすべて、 GraphQL スキーマによって定義されます。 GraphQL API を効果的に使用するには、 Supply Chain Intelligence Suite データ・モデルを十分に理解している必要があります。

開始前に

  • GraphQLを初めて使用する場合は、 GraphQL API の基本に慣れるまで GraphQL チュートリアル を実行してください。
  • Insomニアなどの REST クライアントをインストールします。
  • ブラウザーが GraphiQL ツール用に 適切に構成 されていることを確認します。

このタスクについて

Supply Chain Intelligence Suite データ・モデル・スキーマを学習するための優れた方法は、 GraphQL イントロスペクションを使用することです。 スキーマ・イントロスペクションは、定義されているオブジェクト、タイプに関連付けられているフィールド、列挙型の値、サポートされている照会の種類、照会に使用できるパラメーターなど、スキーマの任意の部分について質問がある場合に役立ちます。

以下のタスクについて学習します。

  • サポートされるすべてのタイプ (オブジェクト、インターフェース、列挙など) を見つける方法。
  • 各タイプの詳細 (オブジェクトのフィールドや列挙型の値など) を見つける方法。
  • サポートされる照会、および照会の詳細 (パラメーターなど)。
  • どの変換がサポートされているか。
  • イントロスペクション結果に基づいて GraphQL 照会を構成する方法。

GraphiQLの文書エクスプローラーを使用できます。

GraphiQL ツールは、イントロスペクション・ロジックを使用して、UI で対話式スキーマ・エクスプローラーを作成します。 ブラウザーで以下の URL を貼り付けて、 GraphiQL インターフェースにナビゲートします。

https://api.ibm.com/infohub/run/graph/na

また、 「資料」 リンクにも注意してください。

GraphiQL 資料

「文書」 リンクをクリックすると、 GraphiQL はスキーマ・イントロスペクション要求を GraphQL API に送信し、応答を解析して文書オブジェクト・モデル (DOM) に変換します。その後、その DOM をナビゲートできます。 その後、 文書エクスプローラー が、モデル内の最上位オブジェクト (この例では query および mutation) のリストとともにレンダリングされます。

GraphiQL 照会およびミューテーションのルート・タイプを示す文書エクスプローラー

このビューでは、ドリルダウンしてすべてのオブジェクトとその属性を探索できます。 例えば、照会にドリルダウンした後、ビューには、照会の eventParams 属性の BusinessEventInput 値が表示されます。

BusinessEvent入力で使用されるフィールドを示す GraphiQL

手順

  1. GraphQL ビジュアル・エディターでスキーマに定義されているすべてのタイプをイントロスペクトします。
    1. ブラウザーに以下の URL を入力して、 GraphiQL ビジュアル・エディターにナビゲートします。
      https://api.ibm.com/infohub/run/graph/na
    2. 以下の GraphQL 照会をエディターの左側に貼り付け、 「実行」をクリックします。
      query {
 __schema {
	    types {
		  name
		  description
		  kind
		}
		queryType {
		  fields {
			name
			description
		  }
		}
   }
 }
      照会が完了すると、エディターの右側に照会応答が表示されます。 応答を調べて、OBJECT、INTERFACE、および ENUM のいくつかの例を見つけます。 OBJECT タイプは、 GraphQL API の基盤です。 各 OBJECT には、データを公開し、名前で照会できるフィールドがあります。 INTERFACE は、OBJECT タイプによってインプリメントされる可能性があるフィールドのリストです。 ENUM タイプは、離散値のセットです。
      スキーマの応答の例
    3. 応答の下部にナビゲートし、サポートされている照会のリストを表示します。
    4. オプション: GraphiQL ビジュアル・エディターで、右上隅のリンクを使用してスキーマ定義を検査します。
  2. Insomニアで同じ GraphQL スキーマ照会を実行します。
    1. 詳しくは、 Get Intelligence Suite schema infoという名前の新規要求を開始してください。
    2. リストから 「POST」 を選択し、以下の URL を入力します。
      https://api.ibm.com/infohub/run/graph/na
    3. 要求本体セクションで、 GraphQL を選択し、前のステップと同じ照会をコピーして 「照会」 ボックスに貼り付けます。
    4. Insomニアで SSL 証明書の検証を無効にします。
    5. 「送信」 をクリックして、要求の応答セクションに応答を表示します。
      応答は、前のステップで受け取った応答と同じでなければなりません。
  3. タイプの詳細をイントロスペクトします。
    1. 以下の照会をInsomニアに入力してください。
        query {
    __type(name: "BusinessObjectsCursor") {
  	...FullType
    }
  }

  fragment FullType on __Type {
    kind
    name
    description
    fields(includeDeprecated: true) {
  	name
  	description
  	args {
  	  ...InputValue
  	}
  	type {
  	  ...TypeRef
  	}
  	isDeprecated
  	deprecationReason
    }

    inputFields {
  	...InputValue
    }

    interfaces {
  	...TypeRef
    }

    enumValues(includeDeprecated: true) {
  	name
  	description
  	isDeprecated
  	deprecationReason
    }

    possibleTypes {
  	...TypeRef
    }
  }

  fragment InputValue on __InputValue {
    name
    description
    type {
  	...TypeRef
    }
    defaultValue
  }

  fragment TypeRef on __Type {
    kind
    name
    ofType {
  	kind
  	name
  	ofType {
  	  kind
  	  name
  	  ofType {
  		kind
  		name
  		ofType {
  		  kind
  		  name
  		  ofType {
  			kind
  			name
  			ofType {
  			  kind
  			  name
  			  ofType {
  				kind
  				name
  			  }
  			}
  		  }
  		}
  	  }
  	}
    }
  }
    2. 受信した応答を調べます。
      BusinessObjectsCursor is an OBJECT type, which implements INTERFACE Cursor. これには、 edges、 pageInfo、および totalCountの 3 つのフィールドが定義されています。 フィールド edges は OBJECT BusinessObjectEdgeの LIST です。 INTERFACE を認識すると、応答の OBJECT タイプが異なる照会を簡素化するのに役立ちます。
      タイプ応答
    3. 照会内のタイプ名を、ステップ 1 または 2で選択した他のタイプに置き換え、照会を再実行し、応答を確認してタイプ定義を理解します。
  4. インターフェースに関連付けられたイントロスペクト・タイプ。
    ステップ 3 に示されている照会はどのタイプにも使用できますが、INTERFACE や ENUM などの特定のタイプに対しては、より単純な応答を使用することをお勧めします。 特定の INTERFACE を実装する OBJECTS のクリーン・リストを取得できます。 GraphQL API クライアントの観点からは、OBJECT が実装する INTERFACE を認識すると、照会応答を簡素化するのに役立ちます。
    1. 以下の照会を使用して、同じ INTERFACE を実装するすべての OBJECTS を検索します。
      query {
__type(name: "Cursor") {
  name
  kind
  description
  possibleTypes {
    name
    kind
    description
  }
}
}
      応答には、 Supply Chain Intelligence Suiteで定義されているすべての Cursor OBJECTS が表示されます。
      インターフェース照会応答
    2. ステップ 1 または 2で識別した別のインターフェースを選択し、それを照会に入れ、実行して関連するすべての OBJECT を見つけます。
  5. ENUM 値をイントロスペクトします。
    Supply Chain Intelligence Suite は、スキーマ内で多数の ENUM を使用します。 ENUM タイプは、一連の離散値を定義します。例えば、 Supply Chain Intelligence Suite ENUM タイプ BusinessObjectType は、スキーマに定義されているすべてのビジネス・オブジェクトのリストを提供します。 このステップでは、ENUM の値リストを取得するための照会を示します。
    1. 以下の照会を任意のツールにコピーして貼り付け、照会を実行します。
      query {
__type(name: "BusinessObjectType") {
  name
  kind
  description
  enumValues {
    name
    description
  }
}
}
      結果を調べて、ENUM BusinessObjectTypeの下にリストされているすべてのオブジェクト・タイプを確認します。 このリストには、API でサポートされるビジネス・データ・オブジェクトが表示されます。
      ENUM 照会応答
    2. タイプを、ステップ 1 または 2 で選択した別の ENUM タイプに置き換え、照会を再実行してその ENUM の値リストを表示します。
  6. イントロスペクト・クエリー定義。
    サポートされるすべての GraphQL 照会は、スキーマ内の特殊なタイプ Query で定義されます。 ステップ 4 で定義した照会を使用して、関連情報を取得できます。
    1. Insomニアで以下の GraphQL 照会を実行します。
        query {
    __type(name: "Query") {
  	...QueryType
    }
  }

  fragment QueryType on __Type {
    fields {
  	name
  	description
  	type {
  		name
  		kind
  	}
  	args {
  	  name
  	  description
  	  type {
  		  name
  		  kind
  	  }
  	}
    }
  }
      応答を調べます。 サポートされる各照会は、応答内のフィールドとして表示されます。 現在、スキーマには合計 4 つの照会が定義されています。 照会の 1 つは businessObjectEventsで、これは BusinessEventCursorを返します。 この照会は 5 つの異なるパラメーターを取ることができ、そのうちの 1 つは advancedFilter OBJECT タイプ BooleanExpです。
      照会定義の応答
  7. ミューテーション定義をイントロスペクトします。
    ミューテーションは、API によってサポートされるすべてのミューテーションを定義するもう 1 つのスキーマ・タイプです。 データのフェッチに使用される GraphQL 照会 API とは異なり、 GraphQL ミューテーション API は、サーバー上のデータを変更するために提供されています。 ステップ 6で使用した照会で Query を Mutation に置き換え、すべての InforHub ミューテーション定義 (つまり、 Supply Chain Intelligence Suite GraphQL API でサポートされるデータ操作の種類) をチェックアウトします。
  8. Supply Chain Intelligence Suiteを構成します。
    これで、サポートされるすべてのタイプを見つける方法と、各タイプの詳細を見つける方法が分かりました。 INTERFACE、ENUM、Query、Mutation のサンプル照会が用意されています。これらの照会には、最初の Supply Chain Intelligence Suite GraphQL 照会の作成を開始するための十分な情報が含まれています。
    1. ステップ 6 の照会を使用して、 businessRuleEventsの照会の定義を見つけます。
    2. ステップ 3 の照会を使用して、応答タイプの詳細を見つけます。
    3. ステップ 3 の照会を使用して、各照会パラメーターの詳細を見つけます。
    4. 前のステップの結果に基づいて、 businessRuleEventsの GraphQL 照会を構成します。