Facultatif : champ d’application, global

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

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

    Vous pouvez obtenir un objet facultatif de cette manière :

    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 facultative 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 Modèle de générateur dans lequel la méthode appelle la chaîne, chaque méthode s’appuyant sur le résultat retourné 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’appelez pas une méthode terminal, une méthode qui renvoie un résultat de requête, ce qui vous permet 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 exécute une requête sur la table Tâche, regroupe les enregistrements par priorité et renvoie chaque priorité dont le total des réaffectations est 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 performance, une requête ne récupère les données que lorsque vous appelez une méthode de terminal. 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 facultatif 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 : filtre (prédicat de fonction)

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

    Tableau 3. Paramètres
    Nom Type Description
    Prédicat Fonction Fonction de 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(Function 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 du résultat 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 Utilisateur 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 lève 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 null ou non définie, le système génère une erreur.

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

    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(Function fn)

    Applique une fonction à l’enregistrement dans un objet facultatif. Si l’objet facultatif 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
    Néant

    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 :
    • true : la requête renvoie null ou undefined.
    • false : 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 :
    • true : la requête renvoie une valeur.
    • false : 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 lazyGetFn)

    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 il 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 retourner 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
    paresseuxGetFn 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 Optional<result>.

    Cet exemple montre comment obtenir un objet facultatif basé sur 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(Function 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 mis à jour par la fonction au format Optional&lt;result>.

    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 (n’importe quelle valeur)

    Entoure une valeur donnée dans un objet facultatif. Par exemple, vous pouvez envelopper le résultat d’une requête GlideRecord dans un objet facultatif 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&lt;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 : orElse(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"
}