Introspection avec GraphQL

GraphQL est un langage de requête basé sur un système de types. Les types GraphQL définissent les objets pris en charge, les zones associées à un objet, les éléments pouvant être interrogés et la manière dont ils sont tous définis par le schéma GraphQL . Pour pouvoir utiliser efficacement les API GraphQL , il est essentiel de bien comprendre le modèle de données Supply Chain Intelligence Suite .

A propos de cette tâche

Un excellent moyen d'apprendre le schéma de modèle de données Supply Chain Intelligence Suite consiste à utiliser l'introspection GraphQL . L'introspection de schéma peut vous aider à chaque fois que vous avez une question sur une partie du schéma, par exemple quels objets sont définis, quelles zones sont associées à un type, quelles sont les valeurs d'une énumération, quels types de requêtes sont pris en charge et quels paramètres peuvent être utilisés pour une requête.

Vous apprendrez à effectuer les tâches suivantes:

• Comment trouver tous les types pris en charge, tels que les objets, les interfaces, l'énumération.
• Comment trouver plus de détails sur chaque type, tels que les zones d'un objet ou les valeurs d'une énumération.
• Les requêtes prises en charge et les détails de la requête, tels que les paramètres.
• Les mutations qui sont prises en charge.
• Comment construire une requête GraphQL basée sur les résultats d'introspection.

Vous pouvez utiliser l'explorateur de documentation dans GraphiQL.

L'outil GraphiQL utilise la logique d'introspection pour générer un explorateur de schémas interactif dans l'interface utilisateur. Accédez à l'interface GraphiQL en collant cette URL dans votre navigateur:

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

Notez également le lien Docs :

Lorsque vous cliquez sur le lien Docs , GraphiQL envoie une demande d'introspection de schéma à l'API GraphQL , puis analyse la réponse dans un modèle d'objet de document (DOM) que vous pouvez ensuite parcourir. L' explorateur de documentation est ensuite rendu, ainsi qu'une liste des objets de niveau supérieur dans le modèle, qui dans cet exemple sont query et mutation.

Dans cette vue, vous pouvez explorer en aval tous les objets et leurs attributs. Par exemple, après avoir effectué un accès au détail de la requête, la vue affiche la valeur BusinessEventInput de l'attribut eventParams pour la requête:

1. Introspection de tous les types définis dans le schéma dans l'éditeur visuel GraphQL .
   1. Accédez à l'éditeur graphique GraphiQL en entrant l'URL suivante dans un navigateur:
      https://api.ibm.com/infohub/run/graph/na
   2. Collez la requête GraphQL suivante dans la partie gauche de l'éditeur et cliquez sur Exécuter.

      query {
       __schema {
      	    types {
      		  name
      		  description
      		  kind
      		}
      		queryType {
      		  fields {
      			name
      			description
      		  }
      		}
         }
       }

      Une fois la requête terminée, vous pouvez voir la réponse à la requête sur le côté droit de l'éditeur. Examinez la réponse et trouvez des exemples d'OBJECT, d'INTERFACE et d'ENUM. Les types OBJECT sont la base des API GraphQL . Chaque objet OBJECT comporte des zones, qui exposent des données et peuvent être interrogées par nom. Les INTERFACE sont une liste de zones qui peuvent être implémentées par des types OBJECT. Les types ENUM sont des ensembles de valeurs discrètes.

      
   3. Accédez au bas de la réponse et affichez la liste des requêtes prises en charge.
   4. Facultatif: Dans l'éditeur visuel GraphiQL , utilisez le lien situé dans l'angle supérieur droit pour inspecter la définition de schéma.
2. Exécutez la même requête de schéma GraphQL dans Insomnia.
   1. Ouvrez Insomnia, lancez une nouvelle demande nommée Get Intelligence Suite schema info.
   2. Sélectionnez POST dans la liste et entrez l'URL suivante:
      https://api.ibm.com/infohub/run/graph/na
   3. Dans la section du corps de demande, sélectionnez GraphQL et copiez et collez la même requête de l'étape précédente dans la zone QUERY .
   4. Désactiver la vérification du certificat SSL dans Insomnia.
   5. Cliquez sur Envoyer et consultez la réponse dans la section de réponse de la demande:
      La réponse doit être identique à celle reçue à l'étape précédente.
3. Introspection des détails du type.
   1. Entrez la requête suivante dans Insomnia:

        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. Examinez la réponse reçue.
      BusinessObjectsCursor est un type OBJECT, qui implémente INTERFACE Cursor. Il comporte trois zones définies: edges, pageInfoet totalCount. La zone edges est une liste d'OBJETS BusinessObjectEdge. La connaissance de l'INTERFACE peut aider à rationaliser les requêtes avec différents types d'objet dans les réponses.
      
   3. Remplacez le nom de type dans la requête par d'autres types que vous avez sélectionnés à l'étape 1 ou 2, exécutez à nouveau la requête et vérifiez les réponses pour comprendre les définitions de type.
4. Types d'introspection associés à une interface.
   Bien que la requête affichée à l'étape 3 puisse être utilisée pour n'importe quel type, vous pouvez préférer des réponses plus simples pour des types spécifiques, tels que INTERFACE ou ENUM. Vous pouvez obtenir une liste propre d'OBJETS qui implémentent une INTERFACE spécifique. Du point de vue du client API GraphQL , la connaissance de l'INTERFACE implémentée par OBJECT peut aider à rationaliser les réponses aux requêtes.
   1. Utilisez la requête suivante pour rechercher tous les objets qui implémentent la même INTERFACE.

      query {
      __type(name: "Cursor") {
        name
        kind
        description
        possibleTypes {
          name
          kind
          description
        }
      }
      }  

      La réponse affiche tous les objets Cursor qui sont définis dans Supply Chain Intelligence Suite.

      
   2. Choisissez une autre interface que vous avez identifiée à l'étape 1 ou 2, placez-la dans la requête et exécutez-la pour rechercher tous les objets associés.
5. Valeurs ENUM d'introspection.
   Supply Chain Intelligence Suite utilise de nombreuses ENUMs dans le schéma. Un type ENUM définit un ensemble de valeurs discrètes. Par exemple, le Supply Chain Intelligence Suite type ENUM BusinessObjectType fournit une liste de tous les objets métier définis dans le schéma. Cette étape montre une requête permettant d'obtenir la liste des valeurs d'un ENUM.
   1. Copiez et collez la requête suivante dans l'outil de votre choix et exécutez-la.

      query {
      __type(name: "BusinessObjectType") {
        name
        kind
        description
        enumValues {
          name
          description
        }
      }
      }

      Vérifiez le résultat pour voir tous les types d'objet répertoriés sous ENUM BusinessObjectType. Cette liste indique les objets de données métier pris en charge dans l'API.

      
   2. Remplacez le type par un autre type ENUM que vous avez sélectionné à l'étape 1 ou 2 et réexécutez la requête pour afficher la liste des valeurs de ce type ENUM.
6. Introspection des définitions de requête.
   Toutes les requêtes GraphQL prises en charge sont définies dans un type spécial Query dans le schéma. Vous pouvez utiliser la requête définie à l'étape 4 pour obtenir les informations associées.
   1. Exécutez la requête GraphQL suivante dans Insomnia:

        query {
          __type(name: "Query") {
        	...QueryType
          }
        }
      
        fragment QueryType on __Type {
          fields {
        	name
        	description
        	type {
        		name
        		kind
        	}
        	args {
        	  name
        	  description
        	  type {
        		  name
        		  kind
        	  }
        	}
          }
        }

      Examinez la réponse. Chaque requête prise en charge est affichée sous la forme d'une zone dans la réponse. Actuellement, quatre requêtes au total sont définies dans le schéma. L'une des requêtes est businessObjectEvents, qui renvoie un BusinessEventCursor. Cette requête peut prendre cinq paramètres différents, dont l'un est advancedFilter de type OBJECT BooleanExp.

      
7. Introspection des définitions de mutation.
   La mutation est un autre type de schéma qui définit toutes les mutations prises en charge par l'API. Contrairement aux API de requête GraphQL qui sont utilisées pour extraire des données, les API de mutation GraphQL sont fournies pour modifier les données sur le serveur. Remplacez Query par Mutation dans la requête utilisée à l'étape 6et consultez toutes les définitions de mutation InforHub , c'est-à-dire le type de manipulation de données pris en charge via l'API Supply Chain Intelligence Suite GraphQL .
8. Construisez votre Supply Chain Intelligence Suite.
   Vous savez maintenant comment trouver tous les types pris en charge et comment trouver les détails de chaque type. Des exemples de requêtes ont été fournis pour INTERFACE, ENUM, Query, Mutation, qui contiennent suffisamment d'informations pour commencer à construire votre première requête Supply Chain Intelligence Suite GraphQL .
   1. Utilisez la requête de l'étape 6 pour trouver la définition d'une requête pour businessRuleEvents.
   2. Utilisez la requête de l'étape 3 pour trouver les détails du type de réponse.
   3. Utilisez la requête de l'étape 3 pour trouver les détails de chaque paramètre de requête.
   4. En fonction des résultats des étapes précédentes, construisez une requête GraphQL pour businessRuleEvents.