Facultatif : dans le champ d’application, global

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

    • L’API facultative interagit avec un seul enregistrement renvoyé par les API GlideQuery, Stream ou GlideRecord , même s’il n’existe pas. Écrivez les scripts moins susceptibles d’entraîner une erreur en gérant les résultats des requêtes nulles ou non définies.

    Vous pouvez obtenir un objet facultatif de l’une des manières suivantes :

    Ces méthodes sont statiques et ne nécessitent pas d’instance de la classe :

    Vous pouvez utiliser ces méthodes statiques avec n’importe quelle API qui renvoie une valeur unique telle que GlideRecord.

    Utilisez l’API en option dans les scripts côté serveur inclus dans le champ d’application ou globaux. Cette API nécessite le module d’extension GlideQuery [com.sn_glidequery].

    Implémentation

    Cette API peut fonctionner avec les API GlideQuery et Stream dans un où les appels de méthode s’enchaînent, chaque méthode s’appuyant sur le résultat renvoyé de la méthode précédente. Utilisez des méthodes pour définir les attributs de la requête. Les méthodes ne s’exécutent pas tant que vous n’avez pas appelé une méthode terminale, une méthode qui renvoie un résultat de requête, vous permettant de définir les exigences de la requête avant de l’exécuter.

    Si la requête renvoie un seul enregistrement, le système enveloppe le résultat dans un objet facultatif. Si la requête renvoie un flux d’enregistrements, le système enveloppe le résultat dans un objet Stream. Ces objets vous permettent de gérer le résultat à l’aide d’un ensemble de méthodes dans chaque API.

    Par exemple, ce script effectue une requête sur la table Tâche, regroupe les enregistrements par priorité et renvoie chaque priorité ayant un total de réaffectations supérieur à quatre.

    var query = new global.GlideQuery('task')
    .where('active', true) //Returns new GlideQuery object with a "where" clause.
    .groupBy('priority') //Returns new GlideQuery object with a "group by" clause.
    .aggregate('sum', 'reassignment_count') //Returns new GlideQuery object with a "sum(reassignment_count)" clause.
    .having('sum', 'reassignment_count', '>', 4) //Returns new GlideQuery object with a "having reassignment_count > 4" clause.
    .select() //Returns a stream of records wrapped in a Stream object.  
    .forEach(function (priority){ //Terminal method in the Stream class that executes the query and returns the result. 
      gs.info("Priority " + priority.group.priority + ": " + priority.sum.reassignment_count + " reassignments");
    });
    Sortie :
    Priority 1: 11 reassignments
Priority 3: 6 reassignments
Priority 5: 5 reassignments

    Méthodes terminales

    Pour des raisons de performances, une requête extrait uniquement les données lorsque vous appelez une méthode terminale. Voici les méthodes terminales de la classe Optional :

    Facultatif : vide (motif de chaîne)

    Renvoie un objet facultatif vide. Utilisez cette méthode dans une clause Else pour gérer une requête susceptible de ne pas renvoyer de résultat.

    Remarque :
    Cette méthode est statique. Vous n’avez pas besoin d’une instance de la classe pour utiliser cette méthode.
    Tableau 1. Paramètres
    Nom Type Description
    motif Chaîne Facultatif. Motif affiché dans le journal lorsque Optional.get() est appelé sur l’objet Optional vide.
    Tableau 2. Renvoie
    Type Description
    Facultatif Objet utilisé pour interagir avec un seul enregistrement.

    Cet exemple vous montre comment générer un objet Optional vide lorsqu’une requête ne renvoie pas de résultat.

    var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

    Sortie :

    NiceError: [2020-08-26T23:23:37.402Z]: get() called on empty Optional: no results

    Facultatif : filter(prédicat de fonction)

    Applique une fonction prédicat, une fonction qui prend une valeur unique et renvoie vrai ou faux, à l’enregistrement à l’intérieur de l’objet facultatif. Si la fonction renvoie la valeur vrai, la méthode renvoie l’enregistrement facultatif non modifié. Si la fonction renvoie la valeur faux, elle renvoie un objet facultatif vide.

    Tableau 3. Paramètres
    Nom Type Description
    prédicat Fonction Fonction prédicat à appliquer à la valeur à l’intérieur de l’objet Facultatif. Doit renvoyer une valeur booléenne.
    Tableau 4. Renvoie
    Type Description
    Facultatif Objet utilisé pour interagir avec un seul enregistrement.

    Cet exemple vous montre comment appliquer une fonction de filtre à un résultat facultatif.

    var filteredQuery = new global.GlideQuery('sys_user')
    .getBy({ sys_id: 'f682abf03710200044e0bfc8bcbe5d38' }, ['phone'])
    .filter(function (user) {
        return phoneRegex.test(user.phone);
    });

    Facultatif : flatMap (fonction fn)

    Applique une fonction qui renvoie un objet facultatif au résultat d’une requête. Utilisez cette méthode pour effectuer une deuxième requête à l’aide des résultats de la première.

    Tableau 5. Paramètres
    Nom Type Description
    Fn Fonction Fonction à appliquer aux résultats de la requête qui a renvoyé l’objet facultatif.
    Tableau 6. Renvoie
    Type Description
    Facultatif Objet utilisé pour interagir avec un seul enregistrement.

    Cet exemple montre comment exécuter une requête de la table User en fonction du résultat d’une requête précédente.

    new global.GlideQuery('alm_asset')
    .whereNotNull('owned_by')
    .selectOne('owned_by')
    .flatMap(function (asset) {
        return new global.GlideQuery('sys_user')
            .getBy({ sys_id: asset.owned_by }, ['first_name', 'last_name', 'company.name'])
    })
    .ifPresent(GQ.jsonDebug);

    Sortie :

    {
  "sys_id": "46d59205a9fe198101d603f5de37bfa3",
  "first_name": "John",
  "last_name": "Bohnhamn",
  "company": {
    "name": "ACME North America"
  }
}

    Facultatif : get()

    Renvoie l’enregistrement à l’intérieur de l’objet facultatif ou génère une erreur si la requête ne renvoie pas d’enregistrement.

    Tableau 7. Paramètres
    Nom Type Description
    Aucun
    Tableau 8. Renvoie
    Type Description
    N'importe lequel L’enregistrement à l’intérieur de l’objet Facultatif. Si la valeur est nulle ou indéfinie, le système génère une erreur.

    Cet exemple montre comment obtenir la valeur d’un seul enregistrement.

    var value = new global.GlideQuery('sys_user')
    .selectOne('first_name') //Returns the result of the query inside an Optional object
    .get(); //Calls Optional.get() on the Optional object

gs.info(JSON.stringify(value));

    Sortie :

    {
   "first_name":"fred",
   "sys_id":"005d500b536073005e0addeeff7b12f4"
}

    Facultatif : ifPresent(fonction fn)

    Applique une fonction à l’enregistrement dans un objet facultatif. Si l’objet Optional ne contient pas d’enregistrement, la fonction ne s’exécute pas.

    Tableau 9. Paramètres
    Nom Type Description
    Fn Fonction Fonction à appliquer à l’enregistrement dans l’objet facultatif.
    Tableau 10. Renvoie
    Type Description
    Aucun

    Cet exemple montre comment imprimer une valeur si elle existe.

    var user = new global.GlideQuery('sys_user')
    .where('sys_id', 'f682abf03710200044e0bfc8bcbe5d38')
    .selectOne('zip')
    .ifPresent(function (user) {
      gs.info('Zip Code: ' + user.zip);
    });

    Facultatif : isEmpty()

    Renvoie la valeur true si l’objet facultatif est vide.

    Tableau 11. Paramètres
    Nom Type Description
    Aucun
    Tableau 12. Renvoie
    Type Description
    Booléen

    Marqueur indiquant si le résultat d’une requête contient une valeur.

    Valeurs valides :
    • vrai : la requête renvoie null ou undefined.
    • faux : la requête renvoie une valeur.

    Cet exemple montre comment vérifier si le résultat d’une requête est vide.

    var checkEmpty = new global.GlideQuery('sys_user')
    .where('last_name', 'Barker')
    .selectOne()
    .isEmpty();

gs.info(checkEmpty);

    Sortie :

    true

    Facultatif : isPresent()

    Vérifie si un objet facultatif contient une valeur.

    Tableau 13. Paramètres
    Nom Type Description
    Aucun
    Tableau 14. Renvoie
    Type Description
    Booléen

    Marqueur indiquant si le résultat d’une requête contient une valeur.

    Valeurs valides :
    • vrai : la requête renvoie une valeur.
    • faux : la requête renvoie null ou undefined.

    Cet exemple montre comment vérifier si une requête renvoie un résultat.

    var checkPresent = new global.GlideQuery('sys_user')    
   .where('last_name', 'Luddy')
   .selectOne('first_name')
   .isPresent();

gs.info(checkPresent);

    Sortie :

    true

    Facultatif : paresseux (Fonction paresseuseGetFn)

    Renvoie un nouvel objet facultatif. Au lieu de contenir l’enregistrement, l’objet contient une fonction permettant d’obtenir l’enregistrement qui n’est appelé que si et quand cela est demandé dans le code.

    Utilisez cette méthode pour retarder l’obtention de la valeur jusqu’à ce qu’elle soit nécessaire. Vous pouvez le faire si vous demandez la valeur à partir d’une source lente et que vous ne voulez pas ralentir inutilement votre code. Sinon, vous pouvez renvoyer un objet facultatif à l’aide des API GlideQuery et Stream .

    Remarque :
    Cette méthode est statique. Vous n’avez pas besoin d’une instance de la classe pour utiliser cette méthode.
    Tableau 15. Paramètres
    Nom Type Description
    lazyGetFn Fonction Fonction qui renvoie un seul enregistrement à la suite d’une requête. Par exemple : 
    var userGr = new GlideRecord('sys_user');
    Tableau 16. Renvoie
    Type Description
    Facultatif Objet contenant le résultat de la requête au format facultatif<résultat>.

    Cet exemple montre comment obtenir un objet facultatif en fonction d’une requête GlideRecord.

    var userOptional = global.Optional.lazy(function () {
    var userGr = new GlideRecord('sys_user');
    userGr.setLimit(1);
    userGr.query();
    return userGr.next() ? userGr.getUniqueValue() : null;
});

gs.info(userOptional);

    Sortie :

    Optional<005d500b536073005e0addeeff7b12f4>

    Facultatif : map(Fonction fn)

    Applique une fonction au résultat d’une requête.

    Tableau 17. Paramètres
    Nom Type Description
    Fn Fonction Fonction à appliquer au résultat de la requête.
    Tableau 18. Renvoie
    Type Description
    Facultatif Objet contenant les résultats de la requête mise à jour par la fonction au format facultatif<résultat>.

    Cet exemple montre comment appliquer une fonction qui transforme une valeur en majuscules au résultat d’une requête.

    var value = new global.GlideQuery('sys_user')
    .whereNotNull('first_name')
    .selectOne('first_name')
    .map(function (user) {
	       return user.first_name.toUpperCase();
    });

gs.info(value);

    Sortie :

    Optional<ABEL>

    Facultatif : de (toute valeur)

    Entoure une valeur donnée dans un objet facultatif. Par exemple, vous pouvez encapsuler le résultat d’une requête GlideRecord dans un objet Optional pour utiliser les méthodes associées.

    Remarque :
    Cette méthode est statique. Vous n’avez pas besoin d’une instance de la classe pour utiliser cette méthode.
    Tableau 19. Paramètres
    Nom Type Description
    valide N'importe lequel Valeur à l’intérieur de l’objet Facultatif.
    Tableau 20. Renvoie
    Type Description
    Facultatif Objet contenant la valeur transmise au format Optional<value>.

    Cet exemple vous montre comment générer un objet facultatif basé sur une requête GlideRecord.

    var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

    Sortie :

    00c269162d761010f87708b56757cbb3

    Facultatif : ouElse (toute valeur par défaut)

    Ajoute une valeur par défaut dans l’objet facultatif si la requête ne renvoie aucun résultat.

    Tableau 21. Paramètres
    Nom Type Description
    defaultValue N'importe lequel Valeur dans l’objet Facultatif si la requête ne renvoie aucun résultat.
    Tableau 22. Renvoie
    Type Description
    N'importe lequel Valeur dans l’objet Facultatif si la requête ne renvoie aucun résultat.

    Cet exemple montre comment renvoyer une valeur, même lorsque la requête est incorrecte.

    var user = new global.GlideQuery('sys_user')
    .get('1234', ['first_name', 'last_name'])
    .orElse({ first_name: 'Default', last_name: 'User' });

gs.info(JSON.stringify(user))

    Sortie :

    {
   "first_name":"Default",
   "last_name":"User"
}