Introspección con GraphQL

GraphQL es un lenguaje de consulta basado en un sistema de tipos. Los tipos GraphQL definen qué objetos están soportados, qué campos están asociados con un objeto y qué se puede consultar y cómo, que está todo definido por el esquema GraphQL . Para poder utilizar las API de GraphQL de forma eficaz, es esencial tener una buena comprensión del modelo de datos de Supply Chain Intelligence Suite .

Acerca de esta tarea

Una gran forma de aprender el esquema de modelo de datos de Supply Chain Intelligence Suite es utilizando la introspección de GraphQL . La introspección de esquema puede ayudarle siempre que tenga una pregunta sobre cualquier parte del esquema, como por ejemplo qué objetos están definidos, qué campos están asociados a un tipo, cuáles son los valores de una enumeración, qué tipo de consultas están soportadas y qué parámetros se pueden utilizar para una consulta.

Aprenderá las tareas siguientes:

• Cómo encontrar todos los tipos soportados, como objetos, interfaces, enumeración.
• Cómo encontrar más detalles de cada tipo, como por ejemplo campos para un objeto o valores de una enumeración.
• Qué consultas están soportadas y los detalles de la consulta, como los parámetros.
• Qué mutaciones están soportadas.
• Cómo construir una consulta GraphQL basada en resultados de introspección.

Puede utilizar el explorador de documentación en GraphiQL.

La herramienta GraphiQL utiliza la lógica de introspección para crear un explorador de esquemas interactivo en la interfaz de usuario. Vaya a la interfaz de GraphiQL pegando este URL en el navegador:

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

Y anote el enlace Docs :

Cuando pulsa el enlace Documentos , GraphiQL envía una solicitud de introspección de esquema a la API de GraphQL y, a continuación, analiza la respuesta en un modelo de objeto de documento (DOM) por el que puede navegar. A continuación, se representa el Explorador de documentación , junto con una lista de los objetos de nivel superior del modelo, que en este ejemplo son query y mutation.

En esta vista, puede detallar más para explorar todos los objetos y sus atributos. Por ejemplo, después de detallar más en la consulta, la vista muestra el valor BusinessEventInput del atributo eventParams para la consulta:

1. Introduzca todos los tipos definidos en el esquema en el editor visual de GraphQL .
   1. Vaya al editor visual de GraphiQL especificando el URL siguiente en un navegador:
      https://api.ibm.com/infohub/run/graph/na
   2. Pegue la siguiente consulta GraphQL en el lado izquierdo del editor y pulse Ejecutar.

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

      Una vez completada la consulta, puede ver la respuesta de la consulta en el lado derecho del editor. Examine la respuesta y busque algunos ejemplos de OBJECT, INTERFACE y ENUM. Los tipos OBJECT son la base de las API de GraphQL . Cada OBJECT tiene campos, que exponen datos y se pueden consultar por nombre. Los INTERFACEs son una lista de campos, que pueden ser implementados por tipos OBJECT. Los tipos ENUM son conjuntos de valores discretos.

      
   3. Vaya a la parte inferior de la respuesta y visualice la lista de consultas soportadas.
   4. Opcional: En el editor visual de GraphiQL , utilice el enlace de la esquina superior derecha para inspeccionar la definición de esquema.
2. Ejecute la misma consulta de esquema GraphQL en Insomnio.
   1. Abrir insomnio, iniciar una nueva solicitud denominada Get Intelligence Suite schema info.
   2. Seleccione POST en la lista y especifique el URL siguiente:
      https://api.ibm.com/infohub/run/graph/na
   3. En la sección de cuerpo de solicitud, seleccione GraphQL y copie y pegue la misma consulta del paso anterior en el recuadro QUERY .
   4. Inhabilitar la verificación de certificados SSL en Insomnia.
   5. Pulse Enviar y consulte la respuesta en la sección de respuesta de la solicitud:
      La respuesta debe ser idéntica a la recibida en el paso anterior.
3. Introspecta los detalles de tipo.
   1. Especifique la consulta siguiente en Insomnio:

        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. Examinar la respuesta que se recibe.
      BusinessObjectsCursor es un tipo OBJECT, que implementa INTERFACE Cursor. Tiene tres campos definidos: edges, pageInfoy totalCount. El campo edges es una LISTA de OBJECT BusinessObjectEdge. Conocer INTERFACE puede ayudar a agilizar las consultas con distintos tipos OBJECT en las respuestas.
      
   3. Sustituya el nombre de tipo en la consulta por otros tipos que haya seleccionado en el paso 1 o 2, vuelva a ejecutar la consulta y compruebe las respuestas para comprender las definiciones de tipo.
4. Tipos de introspección asociados a una interfaz.
   Aunque la consulta que se muestra en el paso 3 se puede utilizar para cualquier tipo, es posible que prefiera respuestas más sencillas para tipos específicos, como por ejemplo INTERFACE o ENUM. Puede obtener una lista limpia de OBJECTS que implementan una INTERFACE específica. Desde la perspectiva del cliente de API de GraphQL , conocer la INTERFAZ que implementa un OBJECT puede ayudar a agilizar las respuestas de las consultas.
   1. Utilice la consulta siguiente para buscar todos los OBJECTS que implementan la misma INTERFACE.

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

      La respuesta muestra todos los objetos Cursor definidos en Supply Chain Intelligence Suite.

      
   2. Elija otra interfaz que haya identificado en el paso 1 o 2, póngelo en la consulta y ejecútelo para buscar todos los OBJECT asociados.
5. Valores ENUM de introspección.
   Supply Chain Intelligence Suite utiliza numerosos ENUMs en el esquema. Un tipo ENUM define un conjunto de valores discretos, por ejemplo, el Supply Chain Intelligence Suite tipo ENUM BusinessObjectType proporciona una lista de todos los objetos de negocio definidos en el esquema. Este paso muestra una consulta para obtener la lista de valores de un ENUM.
   1. Copie y pegue la consulta siguiente en la herramienta que desee y ejecute la consulta.

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

      Compruebe el resultado para ver todos los tipos de objeto que se listan en ENUM BusinessObjectType. Esta lista muestra qué objetos de datos de negocio están soportados en la API.

      
   2. Sustituya el tipo por otro tipo ENUM que haya seleccionado en el paso 1 o 2 y vuelva a ejecutar la consulta para ver la lista de valores para ese ENUM.
6. Definiciones de consulta de introspección.
   Todas las consultas de GraphQL soportadas se definen en un tipo especial Query en el esquema. Puede utilizar la consulta definida en el paso 4 para obtener la información relacionada.
   1. Ejecute la siguiente consulta GraphQL en Insomnio:

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

      Examine la respuesta. Cada consulta soportada se muestra como un campo en la respuesta. Actualmente, hay un total de cuatro consultas definidas en el esquema. Una de las consultas es businessObjectEvents, que devuelve un BusinessEventCursor. Esta consulta puede tomar cinco parámetros diferentes, uno de los cuales es advancedFilter de tipo OBJECT BooleanExp.

      
7. Definiciones de mutación de introspección.
   La mutación es otro tipo de esquema que define todas las mutaciones soportadas por la API. A diferencia de las API de consulta de GraphQL que se utilizan para captar datos, se proporcionan las API de mutación de GraphQL para modificar datos en el servidor. Sustituya Query por Mutation en la consulta que se utiliza en el paso 6y extraiga todas las definiciones de mutación de InforHub , es decir, qué tipo de manipulaciones de datos están soportadas a través de la API de Supply Chain Intelligence Suite GraphQL .
8. Construya el Supply Chain Intelligence Suite.
   Ahora sabe cómo encontrar todos los tipos soportados y cómo encontrar los detalles de cada tipo. Se han proporcionado consultas de ejemplo para INTERFACE, ENUM, Query, Mutation, que contienen información suficiente para empezar a construir la primera consulta de Supply Chain Intelligence Suite GraphQL .
   1. Utilice la consulta del paso 6 para buscar la definición de una consulta para businessRuleEvents.
   2. Utilice la consulta en el paso 3 para buscar los detalles del tipo de respuesta.
   3. Utilice la consulta en el paso 3 para buscar los detalles de cada parámetro de consulta.
   4. Según los resultados de los pasos anteriores, construya una consulta GraphQL para businessRuleEvents.