Créer un schéma GraphQL

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

    • Créez un schéma GraphQL pour rendre les données disponibles pour les requêtes GraphQL.

    Avant de commencer

    Rôle requis : graphql_schema_admin ou admin

    Procédure

    1. Accédez à la Tous > Services web du système > GraphQL > API GraphQL.
    2. Cliquez sur Nouveau.
    3. Renseignez les champs suivants.
      Champ Description
      Nom Nom du schéma.
      Espace de noms du schéma Doit être unique dans le nom de l’application.
      Application Application en lecture seule dont le schéma fait partie.
      Espace de noms de l'application Lecture seule. Fonctionne avec l’espace de noms Schema pour éviter les conflits avec des schémas du même nom.
      Actif Coché si actif, décoché si non actif.
      Schéma Définition de schéma qui adhère au format SDL GraphQL. Doit avoir une syntaxe GraphQL valide. Sinon, des messages d’erreur apparaissent lors de l’enregistrement pour indiquer le problème de syntaxe.
      Remarque :
      Les fonctionnalités GraphQL suivantes ne sont pas prises en charge :
      • Opérations d’abonnement
      • Types de scalaires personnalisés

      Vous pouvez utiliser cette directive dans votre schéma :

      @source : 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.

      Cet exemple définit un type d’objet Incident dans le schéma et utilise un script de résolveur pour mapper ce type à un objet GlideRecord de la table Incident. L’utilisation de la directive @source mappe les champs du type d’incident à la valeur ou aux display_value dans le GlideRecord d’incident.

      type Incident {
    id: String @source(value: "sys_id.value")
    active: Boolean @source(value: "active.display_value")
    state: String @source(value: "state.display_value")    
    priority: String @source(value: "priority.display_value")
    severity: String
    description: DisplayableString
    resolvedBy: User @source(value: "resolved_by.value")
    openedBy: User @source(value: "opened_by.value")
    child_incidents: String
    opened_at: String
    resolved_at: String
    closed_at: String
    work_notes: String    
    comments: String @source(value: "comments.display_value")
    parent_incident: String
}
    4. Sélectionnez l’onglet Sécurité et remplissez le formulaire.
      Champ Description
      Requiert une authentification Coché si le schéma nécessite une authentification, décoché si le schéma ne nécessite pas d’authentification et est disponible publiquement.
      Requiert un rôle SNC interne Apparaît uniquement si le module d’extension Explicit Roles est activé. Coché si le schéma nécessite le rôle interne SNC et décoché si le schéma ne nécessite pas le rôle interne SNC.
      Requiert une autorisation d'ACL Coché si le schéma nécessite une autorisation d’ACL et désactivé si le schéma ne nécessite pas d’autorisation d’ACL.
      ACL S’affiche uniquement si l’option Requiert une autorisation ACL est cochée . Vérifie les requêtes entrantes par rapport aux ACL de type GraphQL.
      Remarque :
      L’API renvoie des messages d’erreur clairs aux utilisateurs qui n’ont pas accès à un schéma ou qui ne sont pas authentifiés lorsque l’API nécessite une authentification pour y accéder.
    5. Enregistrez le formulaire.
    6. Facultatif : Créez un script de résolveur pour définir la valeur renvoyée par le schéma lorsqu’un composant interroge un champ spécifique.
      Si vous ne définissez pas de programme de résolution pour un champ, la requête renvoie toute valeur de champ correspondante du type d’objet parent. Par exemple, supposons que votre schéma dispose d’un type d’objet Incident avec un champ de notes de travail. Le type d’objet Incident possède un résolveur qui est mappé vers un GlideRecord de la table Incident. Si vous ne créez pas de mappage de résolveur pour le champ Notes de travail, le système recherche un champ Notes de travail dans la source de données de l’objet parent, qui est le GlideRecord de la table Incident, et affecte la valeur associée.
      1. Sélectionnez l’onglet Programmes de résolution scriptés GraphQL et cliquez sur Nouveau.
      2. Complétez le formulaire.
        Champ Description
        Nom Nom du programme de résolution
        Schéma Espace de noms de schéma en lecture seule.
        Application Application en lecture seule dont le schéma fait partie.
        Script Définissez la valeur renvoyée lorsque le champ est interrogé. Fonctions disponibles sur l’objet env global :
        • getArguments() : renvoie les arguments du champ précédent.
        • getSource() : renvoie l’objet parent.

        Ce script a accès à GlideRecord.

        Cet exemple renvoie un enregistrement de la table Utilisateur lorsque le champ associé est interrogé :

        (function process(/*ResolverEnvironment*/ env) {

    var userid = env.getArguments().id != null ? env.getArguments().id : env.getSource();
    var now_GR = new GlideRecord('sys_user');
    gr.addQuery('sys_id', userid);
    gr.queryO;
    return gr;

})(env);
      3. Cliquez sur Envoyer.
    7. Facultatif : Définissez les résolveurs de type pour votre schéma afin de résoudre les interfaces et les unions en types concrets.
      1. Sélectionnez l’onglet Solveurs de types scriptés GraphQL et cliquez sur Nouveau.
      2. Complétez le formulaire.
        Champ Description
        Schéma Espace de noms de schéma en lecture seule.
        Type Type d’interface ou d’union défini dans le schéma.
        Application Application en lecture seule dont le schéma fait partie.
        Script Définissez la valeur retournée pour les types d’union et d’interface. Fonctions 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.

        Ce script a accès à GlideRecord.
      3. Cliquez sur Envoyer.
    8. Facultatif : Mappez les enregistrements resolver et typeresolver aux champs du schéma.
      Ce mappage permet au système de savoir quelle valeur renvoyer lorsqu’un composant interroge un champ spécifique.
      1. Sélectionnez l’onglet Mappages du résolveur scripté GraphQL et cliquez sur Nouveau.
      2. Complétez le formulaire.
        Champ Description
        Chemin Chemin d’accès au champ dans le schéma que vous souhaitez mapper.
        Programme de résolution Programme de résolution à utiliser pour définir les données renvoyées par le champ.
        Application Application en lecture seule dont le schéma fait partie.
        Schéma Espace de noms de schéma en lecture seule.
      3. Cliquez sur Envoyer.