Créer un schéma GraphQL

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 5 minutes de lecture

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

    Avant de commencer

    Rôle requis : graphql_schema_admin ou admin

    Procédure

    1. Accédez à la Tout > Services web du système > GraphQL > API GraphQL.
    2. Sélectionnez 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 les schémas portant le même nom.
      Actif Option permettant d’activer ou de désactiver le schéma GraphQL.
      Schéma Définition de schéma qui adhère au format SDL GraphQL. La syntaxe GraphQL doit être valide. Dans le cas contraire, des messages d’erreur s’affichent 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 scalaires personnalisés

      Vous pouvez utiliser cette directive dans votre schéma :

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

      Cet exemple définit un type d’objet Incident dans le schéma et utilise un script de résolveur pour mapper le type à un GlideRecord à partir de la table Incident. L’utilisation de la directive @source mappe les champs du type d’incident à la valeur ou au 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. Dans la section Sécurité , renseignez les champs.
      Champ Description
      Requiert une authentification Sélectionnez cette option pour exiger une authentification afin d’accéder au schéma. Si vous désactivez cette option, le schéma est disponible publiquement.
      Requiert une autorisation d'ACL Sélectionnez cette option pour exiger l’autorisation ACL de l’ensemble de l’API. Dans le champ ACL, sélectionnez ACL de type GraphQL.

      Pour utiliser l’autorisation ACL uniquement pour des chemins spécifiques, laissez cette option décochée et spécifiez le niveau par rapport auquel évaluer les ACL dans le champ de profondeur ACL de chemin.
      Exige un rôle SNC interne Sélectionnez cette option si le schéma nécessite le rôle interne SNC. Cette option s’affiche uniquement si le module d’extension Explicit Roles (com.glide.explicit_roles) est activé.
      Profondeur ACL du chemin Spécifiez le niveau de l’API GraphQL auquel appliquer les ACL. Définir la profondeur du chemin d’accès sur 3 ou moins utilise moins de ressources et permet de renvoyer des réponses de requête.

      Pour spécifier les ACL à utiliser pour le chemin d’accès, vous devez créer un ACL de type GraphQL et ajouter le chemin d’accès exact de l’API en commençant par l’espace de noms du schéma dans le champ Nom . Par exemple : /<planet>/<findAll>/<name>. Les caractères génériques ne sont pas pris en charge. Pour plus d'informations, consultez Configure an ACL rule.

      Remarque :
      Le champ ACL s’applique à l’ensemble de l’API et est indépendant des ACL appliquées à des chemins spécifiques.
      ACL Sélectionnez les ACL de type GraphQL pour vérifier les requêtes entrantes. Les ACL que vous sélectionnez s’appliquent à l’ensemble de l’API. Cette option s’affiche uniquement si l’option Requiert une autorisation d’ACL est sélectionnée.
      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.
      Si vous ne définissez pas de programme de résolution pour un champ, la requête renvoie toute valeur de champ correspondante à partir du type d’objet parent. Par exemple, supposons que votre schéma comporte un type d’objet Incident avec un champ de notes de travail. Le type d’objet Incident dispose d’un résolveur qui est mappé à un GlideRecord à partir 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 sélectionnez Nouveau.
      2. Renseignez 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. Sélectionnez Soumettre.
    7. Facultatif : Définissez les résolveurs de types pour votre schéma afin de résoudre les interfaces et les unions en types concrets.
      1. Sélectionnez l’onglet BatchQL scripted Type Resolvevers, puis sélectionnez Nouveau.
      2. Renseignez le formulaire.
        Champ Description
        Schéma Espace de noms de schéma en lecture seule.
        Type Le 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. Sélectionnez Soumettre.
    8. Facultatif : Mappez les enregistrements du programme de résolution et du résolveur de type aux champs du schéma.
      Ce mappage indique au système la valeur à renvoyer lorsqu’un composant interroge un champ.
      1. Sélectionnez l’onglet Mappages du programme de résolution scripté GraphQL et sélectionnez Nouveau.
      2. Renseignez le formulaire.
        Champ Description
        Chemin d'accès Chemin d’accès au champ dans le schéma que vous souhaitez mapper.
        Programme de résolution Résolveur à utiliser pour définir les données retourné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. Sélectionnez Soumettre.