Interroger les données d’enregistrement à l’aide de l’infrastructure de l’API GraphQL

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 4 minutes de lecture

    • Créez une API GraphQL personnalisée pour interroger les données d’enregistrement 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 le Cadre de travail de l'interface utilisateur Next Experience pour 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 de la table Ticket.

    Pour en savoir plus sur le développement de composants, consultez 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étectez les champs et les objets pouvant faire l’objet d’une requête via 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.
    • Connaissance générale des concepts des composants Web.
    • Composant personnalisé Espace de travail pour utiliser 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 des 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 Script de schéma dans 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 renvoyé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 TypeResolveurs scriptés GraphQL sur le formulaire Schémas scriptés GraphQL.
    Mappages du programme de résolution
    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 GraphQL.

    Pour tester les requêtes sur vos API GraphQL, vous pouvez utiliser GraphQL Explorer, 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 de 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 à 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
    L’espace de noms pour l’application personnalisée. Pour en savoir plus sur les espaces de noms de l’application, consultez Périmètre de l’application.
    Espace de noms du schéma
    L’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 de 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 : planet
    query {
  x_graph_scope {
    planet {
      findAll {
        name
        mass
        distance
      }
    }
  }
}

    Directives et fonctions globales

    @source directive de schéma

    Mappe un champ GraphQL sur la valeur d’une propriété de l’objet parent. Si le champ dispose d’un script de résolution distinct, le système utilise l’enregistrement qu’il résout au lieu de l’objet parent.

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

    @defer directive query
    Différez le traitement d’un fragment GraphQL à plus tard dans la requête. Utilisez cette directive de requête pour retarder le renvoi des données pour les champs à réponse lente dans un fragment. Diffusez les résultats de champ du fragment différé en tant que 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 de requête 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 de résolveur

    Ces fonctions sont disponibles sur l’objet env global.

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

    Utilisez-le 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 GraphQL PTO de démonstration avec des mutations et des requêtes, activez le module d’extension GraphQL Framework Demo Application (com.glide.graphql.framework.demo).