Interroger les données des enregistrements à l’aide du cadre de travail de l’API GraphQL

Créez une API GraphQL personnalisée pour interroger les données d’enregistrement à partir d’un composant ou d’un système tiers.

Par exemple, vous pouvez créer un composant qui affiche les tickets associés à un SLA. Vous pouvez utiliser pour Cadre de travail de l'interface utilisateur Next Experience développer le composant dont vous avez besoin et accéder aux données de ticket à partir de la plateforme en créant un schéma GraphQL qui définit les données dans la table Ticket.

Pour en savoir plus sur le développement de composants, reportez-vous à la section Développement de composants pour Workspace.

Avantages de GraphQL

GraphQL est un langage de requête web optimisé pour le développement côté client. À l’aide de GraphQL scripté, vous pouvez :

• Découvrez les champs et les objets qui peuvent être interrogés par le biais de l’introspection.
• Interrogez les données exactes dont vous avez besoin à partir d’un composant.
• Gérez plusieurs requêtes possibles à partir d’une seule API, par opposition à plusieurs points de terminaison pour une demande REST.
• Intégrez à des systèmes tiers en rendant le schéma public.
• Générez la requête GraphQL à partir de votre composant et gérez la réponse.

À savoir avant de commencer

Avant de commencer à créer des API GraphQL personnalisées, assurez-vous d’avoir :

• Connaissances GraphQL pour créer un schéma.
• Connaissances JavaScript pour définir le comportement de l’API.
• Connaissances générales des concepts des composants Web.
• Composant personnalisé Espace de travail pour consommer les données d’enregistrement.
• Compréhension du modèle de ServiceNow données que vous souhaitez exposer dans le schéma.
• Connaissances GlideRecord pour mapper les champs afin d’enregistrer des données dans vos scripts de résolveur.

Vue d’ensemble de GraphQL

La création d’une API GraphQL scriptée comprend les parties suivantes :

Langage de définition de schéma GraphQL (SDL)

Définissez la structure et le type de données des champs disponibles dans une requête GraphQL. Vous pouvez définir le SDL à l’aide du champ de script de schéma de la table Schémas scriptés GraphQL [sys_graphql_schema]. Le SDL ne prend en charge que les opérations de requête et de mutation.

Programmes de résolution

Définissez les données retournées par chaque champ. Vous pouvez définir les résolveurs pour chaque champ dans la liste connexe Résolveurs scriptés GraphQL sur le formulaire Schémas scriptés GraphQL.

TypeResolvevers

Résolvez les interfaces et les unions en types GraphQL concrets. Par exemple, vous pouvez définir une union entre un type d’incident et un type de problème . Utilisez le script typeresolver pour définir quand renvoyer lequel. Vous pouvez définir les typeresolvevers dans la liste connexe Typeresolvevers scriptés GraphQL sur le formulaire Schémas scriptés GraphQL.

Mappages de résolveur

Mappez les résolveurs aux champs du schéma. Vous pouvez définir des mappages de résolveur dans la liste connexe Mappages de résolveur scriptés GraphQL sur le formulaire Schémas scriptés GraphQL.

Pour en savoir plus sur le langage de requête GraphQL, consultez le site Web de GraphQL.

Pour tester les requêtes de vos API GraphQL, vous pouvez utiliser l’explorateur GraphQL, un outil de test GraphQL intégré. Pour plus d'informations, consultez Tester les API GraphQL avec l’explorateur GraphQL.

Limitations

Les fonctionnalités GraphQL suivantes ne sont pas prises en charge :

• Opérations d’abonnement
• Types scalaires personnalisés

Introspection

Par défaut, les requêtes introspectives dans vos schémas personnalisés ne sont pas activées. Pour activer l’introspection, reportez-vous à la section Activer les requêtes introspectives pour les schémas GraphQL.

Espaces de noms

Les API GraphQL ont deux espaces de noms différents :

Espace de noms de l'application

Espace de noms pour l’application personnalisée. Pour en savoir plus sur les espaces de noms d’application, consultez Périmètre de l’application.

Espace de noms du schéma

Espace de noms pour le schéma afin de garantir que toutes les requêtes sont uniques. Vous pouvez avoir plusieurs espaces de noms de schéma dans une seule application.

Lors de l’interrogation des données, vous devez inclure les deux espaces de noms dans votre requête. Par exemple, la requête suivante recherche des données avec les espaces de noms suivants :

• Espace de noms de l’application : x_graph_scope
• Espace de noms du schéma : planète

query {
  x_graph_scope {
    planet {
      findAll {
        name
        mass
        distance
      }
    }
  }
}

Directives et fonctions globales

@source directive de schéma

Mappe un champ GraphQL à la valeur d’une propriété de l’objet parent. Si le champ possède un script de résolveur distinct, le système utilise l’enregistrement qu’il résout à la place de l’objet parent.

Utilisez la directive @source dans votre script de schéma.

@defer directive de requête

Différer le traitement d’un fragment GraphQL à plus tard dans la requête. Utilisez cette directive de requête pour retarder le renvoi de données pour les champs à réponse lente au sein d’un fragment. Diffusez les résultats de champ du fragment différé sous la forme d’une réponse en plusieurs parties.

Remarque :

Pour utiliser la directive @defer , votre client GraphQL doit accepter les en-têtes HTTP en plusieurs parties/mixtes. Par exemple, définissez les en-têtes HTTP sur Accept : multipart/mixed ; boundary= »-« .

Utilisez la directive @defer pour améliorer le délai d’interaction de l’utilisateur. Évitez d’appliquer cette directive query sans discernement, car elle peut également entraîner des dégradations des performances. Effectuez des tests de performance pour déterminer quels champs peuvent être différés pour de meilleures performances.

Fonctions du programme de résolution

Ces fonctions sont disponibles sur l’objet env global.

• getArguments() : renvoie les arguments du champ précédent.
• getSource() : renvoie l’objet parent.

À utiliser dans votre script de résolveur.

Fonctions Typeresolver

Ces fonctions sont disponibles sur l’objet env global.

• getArguments() : renvoie les arguments du champ précédent.
• getObject() : renvoie l’objet parent.
• getTypeName() : renvoie le nom de l’interface ou du type d’union.

À utiliser dans votre script typeresolver.

Application de démonstration

Pour afficher un schéma de calendrier PTO GraphQL de démonstration avec des mutations et des requêtes, activez le module d’extension GraphQL Framework Demo Application (com.glide.graphql.framework.demo).

• Créer un schéma GraphQL
  Créez un schéma GraphQL pour rendre les données disponibles aux requêtes GraphQL.
• Activer les requêtes introspectives pour les schémas GraphQL
  Découvrez les requêtes et les mutations prises en charge par les schémas sur votre instance en activant l’introspection.
• Tester les API GraphQL avec l’explorateur GraphQL
  Testez vos API GraphQL à l’aide d’un outil de test GraphQL intégré.
• Interroger un schéma GraphQL à partir d’un composant
  Accédez aux données d’enregistrement dans un composant en interrogeant votre schéma GraphQL scripté.
• Propriétés système GraphQL
  Configurez le comportement du cadre de travail de l’API GraphQL. Par exemple, vous pouvez configurer si vous souhaitez autoriser les requêtes introspectives dans votre schéma.