Introspezione con GraphQL

GraphQL è un linguaggio di query basato su un sistema tipo. I tipi GraphQL definiscono quali oggetti sono supportati, quali campi sono associati a un oggetto, cosa può essere interrogato e come, che è tutto definito dallo schema GraphQL . Per poter utilizzare efficacemente le API GraphQL , è essenziale avere una buona conoscenza del modello di dati Supply Chain Intelligence Suite .

Informazioni su questa attività

Un ottimo modo per apprendere lo schema del modello dati Supply Chain Intelligence Suite consiste nell'utilizzare l'introspezione GraphQL . L'introspezione dello schema può essere utile ogni volta che si ha una domanda su qualsiasi parte dello schema, ad esempio quali oggetti sono definiti, quali campi sono associati a un tipo, quali sono i valori di un'enumerazione, quale tipo di query è supportato e quali parametri possono essere utilizzati per una query.

Si apprendono le seguenti attività:

• Come trovare tutti i tipi supportati, come oggetti, interfacce, enum.
• Come trovare ulteriori dettagli di ciascun tipo, ad esempio campi per un oggetto o valori di un'enumerazione.
• Le query supportate e i relativi dettagli, ad esempio i parametri.
• Quali mutazioni sono supportate.
• Come creare una query GraphQL basata sui risultati dell'introspezione.

È possibile utilizzare Esplora documentazione in GraphiQL.

Lo strumento GraphiQL utilizza la logica di introspezione per creare un Esplora schema interattivo nell'interfaccia utente. Passare all'interfaccia GraphiQL incollando questo URL nel browser:

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

Nota il link Docs :

Quando fai clic su Docs , GraphiQL invia una richiesta di introspezione dello schema all'API GraphQL , quindi analizza la risposta in un DOM (document object model) che puoi quindi esplorare. Viene quindi eseguito il rendering di Esplora documentazione , insieme a un elenco degli oggetti di livello superiore nel modello, che in questo esempio sono query e mutation.

In questa vista, è possibile eseguire il drill down per esplorare tutti gli oggetti e i loro attributi. Ad esempio, dopo aver eseguito il drill nella query, la vista mostra il valore BusinessEventInput dell'attributo eventParams per la query:

1. Introesamina tutti i tipi definiti nello schema nell'editor visivo GraphQL .
   1. Passare all'editor visivo GraphiQL immettendo il seguente URL in un browser:
      https://api.ibm.com/infohub/run/graph/na
   2. Incollare la seguente query GraphQL sul lato sinistro dell'editor e fare clic su Esegui.

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

      Una volta completata la query, è possibile visualizzare la risposta della query sul lato destro dell'editor. Esaminare la risposta e trovare alcuni esempi di OBJECT, INTERFACE e ENUM. I tipi OBJECT sono la base delle API GraphQL . Ogni OBJECT ha campi, che espongono dati e possono essere interrogati per nome. Gli INTERFACE sono elenchi di campi, che potrebbero essere implementati dai tipi OBJECT. I tipi ENUM sono insiemi di valori discreti.

      
   3. Andare alla fine della risposta e visualizzare l'elenco di query supportate.
   4. Facoltativo: nell'editor visivo GraphiQL , utilizzare il link nell'angolo in alto a destra per esaminare la definizione dello schema.
2. Eseguire la stessa query di schema GraphQL in Insomnia.
   1. Aprire Insomnia, avviare una nuova richiesta denominata Get Intelligence Suite schema info.
   2. Selezionare POST dall'elenco e immettere il seguente URL:
      https://api.ibm.com/infohub/run/graph/na
   3. Nella sezione del corpo della richiesta, selezionare GraphQL e copiare e incollare la stessa query dal passo precedente nella casella QUERY .
   4. Disabilita verifica certificato SSL in Insomnia.
   5. Fare clic su Invia e visualizzare la risposta nella sezione di risposta della richiesta:
      La risposta deve essere identica a quella ricevuta nel passo precedente.
3. Controllare i dettagli del tipo.
   1. Immettere la seguente query in 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. Esaminare la risposta ricevuta.
      BusinessObjectsCursor è un tipo OBJECT, che implementa INTERFACE Cursor. Dispone di tre campi definiti: edges, pageInfoe totalCount. Il campo edges è un ELENCO di OGGETTO BusinessObjectEdge. Conoscere l'INTERFACCIA può aiutare a semplificare le query con diversi tipi OBJECT nelle risposte.
      
   3. Sostituisci il nome del tipo nella query con altri tipi scelti al passo 1 o 2, esegui nuovamente la query e controlla le risposte per comprendere le definizioni del tipo.
4. Controllare i tipi associati a un'interfaccia.
   Sebbene la query mostrata nel passo 3 possa essere utilizzata per qualsiasi tipo, potresti preferire risposte più semplici per tipi specifici, come INTERFACE o ENUM. È possibile ottenere una lista pulita di OGGETTI che implementano una specifica INTERFACCIA. Dalla prospettiva del client API GraphQL , conoscere l'INTERFACCIA implementata da OBJECT può aiutare a semplificare le risposte alle query.
   1. Utilizzare la seguente query per trovare tutti gli OBJECTS che implementa lo stesso INTERFACE.

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

      La risposta mostra tutti gli Cursor OBJECTS definiti in Supply Chain Intelligence Suite.

      
   2. Selezionare un'altra interfaccia identificata nel passo 1 o 2, inserirla nella query ed eseguirla per trovare tutti gli oggetti associati.
5. Introspect ENUM values.
   Supply Chain Intelligence Suite utilizza numerosi ENUM nello schema. Un tipo ENUM definisce una serie di valori discreti, ad esempio il Supply Chain Intelligence Suite tipo ENUM BusinessObjectType fornisce un elenco di tutti gli oggetti di business definiti nello schema. Questo passo mostra una query per ottenere l'elenco di valori di un ENUM.
   1. Copiare e incollare la query seguente nello strumento desiderato ed eseguire la query.

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

      Controllare il risultato per visualizzare tutti i tipi di oggetto elencati in ENUM BusinessObjectType. Questo elenco mostra quali oggetti di dati aziendali sono supportati nell'API.

      
   2. Sostituire il tipo con un altro tipo di ENUM selezionato al passo 1 o 2 ed eseguire nuovamente la query per visualizzare l'elenco di valori per tale ENUM.
6. Introspect query definitions.
   Tutte le query GraphQL supportate sono definite in un tipo speciale Query nello schema. È possibile utilizzare la query definita nel passo 4 per ottenere le informazioni correlate.
   1. Esegui la seguente query GraphQL in Insomnia:

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

      Esaminare la risposta. Ogni query supportata viene mostrata come un campo nella risposta. Attualmente, nello schema sono definite un totale di quattro query. Una delle query è businessObjectEvents, che restituisce un BusinessEventCursor. Questa interrogazione può assumere cinque parametri diversi, uno dei quali è advancedFilter di tipo OBJECT BooleanExp.

      
7. Introspect mutation definitions.
   La mutazione è un altro tipo di schema che definisce tutte le mutazioni supportate dall'API. A differenza delle API di query GraphQL utilizzate per recuperare i dati, le API di mutazione GraphQL vengono fornite per modificare i dati sul server. Sostituisci Query con Mutation nella query utilizzata nel passo 6e controlla tutte le definizioni di mutazione InforHub , ossia il tipo di manipolazione dei dati supportato tramite l'API Supply Chain Intelligence Suite GraphQL .
8. Crea il tuo Supply Chain Intelligence Suite.
   Ora sai come trovare tutti i tipi supportati e come trovare i dettagli di ogni tipo. Sono state fornite query di esempio per INTERFACE, ENUM, Query, Mutation, che contengono informazioni sufficienti per iniziare a creare la prima query Supply Chain Intelligence Suite GraphQL .
   1. Utilizzare la query nel passo 6 per trovare la definizione di una query per businessRuleEvents.
   2. Utilizzare la query nel passo 3 per trovare i dettagli del tipo di risposta.
   3. Utilizzare la query nel passo 3 per trovare i dettagli di ciascun parametro di query.
   4. In base ai risultati delle fasi precedenti, creare una query GraphQL per businessRuleEvents.