Créer un schéma GraphQL

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 5 minutes de lecture

    • Créez un schéma GraphQL pour mettre les données à la disposition des 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. 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 tout conflit avec les schémas portant le même nom.
      Actifs Option permettant d’activer ou de désactiver le schéma GraphQL.
      Schéma Définition de schéma qui adhère au format GraphQL SDL. Doit être de syntaxe GraphQL valide. Sinon, des messages d’erreur apparaissent à 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 à la valeur d’une propriété de l’objet parent. Si le champ possède un script de résolution distinct, le système utilise l’enregistrement dans lequel 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ésolution pour mapper le type à un GlideRecord de la table Incident. À l’aide de la directive @source mappe les champs du type d’incident à la valeur ou à la display_value du 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 les 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 Profondeur ACL du chemin d’accès .
      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. La définition de la profondeur du chemin d’accès sur 3 ou moins utilise moins de ressources et permet de renvoyer des réponses à la requête.

      Pour spécifier les ACL à utiliser pour le chemin d’accès, vous devez créer une 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 par rapport auxquelles 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ésolution pour définir la valeur renvoyée par le schéma lorsqu’un composant interroge un champ.
      Si vous ne définissez pas de résolveur pour un champ, la requête renvoie toute valeur de champ correspondante du type d’objet parent. Par exemple, supposons que votre schéma comprenne un type d’objet avec un champ worknotes. Le type d’objet Incident dispose d’un programme de résolution qui est mappé à un GlideRecord de la table Incident. Si vous ne créez pas de mappage de résolveur pour le champ des notes de travail, le système recherche un champ de 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 Résolveurs 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 de votre schéma pour résoudre les interfaces et les unions en types concrets.
      1. Sélectionnez l’onglet Résolveurs de type scripté GraphQL et 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 renvoyé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 programme de résolution 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 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. Sélectionnez Soumettre.