Flux - Inclus, global

L’API de flux fournit des méthodes pour interagir avec un flux d’éléments tels que des enregistrements. Par exemple, vous pouvez utiliser la méthode forEach() pour mettre à jour l’état de chaque enregistrement dans un flux renvoyé par l’API GlideQuery .

Vous pouvez obtenir un objet Stream de la manière suivante :

• Instanciez un objet Stream à l’aide du constructeur.
• Renvoyer un objet Stream à partir de la méthode GlideQuery.select(). Pour plus d’informations, consultez GlideQuery.

Cette méthode est statique et ne nécessite pas d’instance de la classe : fromArray().

Utilisez l’API de flux dans des 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 l’API GlideQuery et l’API facultative dans un Modèle de générateur où 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’avez pas appelé 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 ne renvoie qu’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é 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 performances, une requête ne récupère des données que lorsque vous appelez une méthode terminale. Voici les méthodes terminales de la classe Stream :

• chaque()
• find()
• forEach()
• réduire()
• certains()
• toArray()

Stream : Stream(Function nextFn)

Instancie un objet Stream.

Au lieu d’utiliser ce constructeur, vous pouvez renvoyer un objet Stream basé sur une requête à l’aide de l’API GlideQuery .

Tableau 1. Paramètres

Nom	Type	Description
nextFn	Fonction	Fonction qui récupère l’élément suivant dans le flux.

Cet exemple vous montre comment créer un objet Stream basé sur un générateur de nombres aléatoires. Assurez-vous d’inclure la méthode limit() pour éviter de créer une boucle infinie.

new Stream(Math.random)
   .map(Math.round)
   .map(function (num) { 
      return num === 1 ? 'heads' : 'tails'; 
   })
   .limit(10)
   .forEach(gs.info)

Sortie :

*** Script: tails
*** Script: heads
*** Script: tails
*** Script: heads
*** Script: tails
*** Script: heads
*** Script: tails
*** Script: tails
*** Script: tails
*** Script: tails

Flux : bloc (nombre de nombres)

Renvoie les résultats sous forme de lots de tableaux, chacun contenant le nombre d’enregistrements transmis à la méthode.

Tableau 2. Paramètres

Nom	Type	Description
compter	Numéro	Nombre d’enregistrements dans chaque tableau renvoyés à partir du flux.

Tableau 3. Renvoie

Type	Description
Flux	Objet utilisé pour interagir avec un flux d’éléments tels que des enregistrements.

Cet exemple montre comment interroger une table et fractionner le résultat en lots de tableaux.

var chunkResult = new GlideQuery('cmdb_ci_hardware')
    .select('asset', 'purchase_date')
    .limit(10)
    .chunk(5) //Returns arrays of 5 sys_ids at a time
    .forEach(function (chunk){ 
        gs.info(JSON.stringify(chunk, null, 2)); 
    });

Sortie :

*** Script: [
  {
    "asset": "2fa9680d3790200044e0bfc8bcbe5dfb",
    "purchase_date": "2022-02-28",
    "sys_id": "2ba9680d3790200044e0bfc8bcbe5dfc"
  },
  {
    "asset": "73c1fa8837f3100044e0bfc8bcbe5ded",
    "purchase_date": "2017-12-05",
    "sys_id": "b4fd7c8437201000deeabfc8bcbe5dc1"
  },
  {
    "asset": "cbc1ba8837f3100044e0bfc8bcbe5dad",
    "purchase_date": "2017-12-05",
    "sys_id": "25fd3c8437201000deeabfc8bcbe5dea"
  },
  {
    "asset": "8fc1ba8837f3100044e0bfc8bcbe5da9",
    "purchase_date": null,
    "sys_id": "108a9205c611227500786e160f9d343e"
  },
  {
    "asset": "27c1fa8837f3100044e0bfc8bcbe5dd8",
    "purchase_date": "2017-06-06",
    "sys_id": "a9a2d111c611227601fb37542399caa8"
  }
]
*** Script: [
  {
    "asset": "93c1fa8837f3100044e0bfc8bcbe5d30",
    "purchase_date": "2017-12-05",
    "sys_id": "6b43105c37301000deeabfc8bcbe5db2"
  },
  {
    "asset": "a2c0b1213784200044e0bfc8bcbe5de3",
    "purchase_date": "2017-12-05",
    "sys_id": "aac0b1213784200044e0bfc8bcbe5de3"
  },
  {
    "asset": "33c1fa8837f3100044e0bfc8bcbe5def",
    "purchase_date": "2017-12-05",
    "sys_id": "d0e8761137201000deeabfc8bcbe5da7"
  },
  {
    "asset": "53c1fa8837f3100044e0bfc8bcbe5d1f",
    "purchase_date": "2017-12-05",
    "sys_id": "53fdbc8437201000deeabfc8bcbe5d10"
  },
  {
    "asset": "f1c031213784200044e0bfc8bcbe5de0",
    "purchase_date": "2017-12-05",
    "sys_id": "71c031213784200044e0bfc8bcbe5de1"
  }
]

Cet exemple montre comment créer une requête enfant à l’aide de lots d’ID. Lorsque vous appelez la méthode flatMap() après avoir utilisé la méthode chunk(), le système itère sur le lot d’enregistrements au lieu de chaque enregistrement individuel.

var chunkResult = new global.GlideQuery('cmdb_ci_hardware')
    .select('sys_id')
    .map(function (device) { return device.sys_id; })
    .chunk(5) //Returns arrays of 5 sys_ids at a time
    .flatMap(function (deviceIds) {
        return new GlideQuery('cmdb_sam_sw_install')
            .where('installed_on', 'IN', deviceIds)
            .select('software_model', 'installed_on');
    })

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

Flux : every (prédicat de fonction)

Applique une fonction de prédicat à chaque élément de l’objet Stream. Si le prédicat renvoie true pour chaque élément du flux, la méthode retourne true. Si le prédicat renvoie false pour un élément du flux, la méthode retourne false.

Tableau 4. Paramètres

Nom	Type	Description
prédicat	Fonction	Fonction de prédicat à appliquer à chaque enregistrement ou élément à l’intérieur de l’objet Stream. La fonction doit prendre chaque élément du flux comme entrée et renvoyer un booléen.

Tableau 5. Renvoie

Type	Description
Booléen	Marqueur indiquant si la fonction de prédicat renvoie la valeur vrai pour chaque élément du flux. Valeurs valides : true : la fonction de prédicat renvoie la valeur true pour chaque élément du flux. false : la fonction de prédicat ne renvoie pas true pour chaque élément du flux.

Cet exemple montre comment appliquer une fonction de prédicat à chaque élément d’un flux.

var hasOnlyShortDescriptions = new global.GlideQuery('task')
   .whereNotNull('description')
   .select('description')
   .every(function (t) { 
       return t.description.length < 10; 
       });

gs.info(hasOnlyShortDescriptions);

Sortie :

false

Flux : filtre (prédicat de fonction)

Applique une fonction de prédicat à chaque élément de l’objet Stream. Si le prédicat renvoie true, la méthode retourne le flux. Si le prédicat renvoie false, il renvoie un objet Stream vide.

Pour de meilleures performances, utilisez les méthodes where(), whereNotNull() et whereNull() dans la classe GlideQuery au lieu de cette méthode lorsque cela est possible. Voir GlideQuery.

Tableau 6. Paramètres

Nom	Type	Description
prédicat	Fonction	Fonction de prédicat à appliquer à chaque enregistrement ou élément à l’intérieur de l’objet Stream. La fonction doit prendre chaque élément du flux comme entrée et renvoyer un booléen.

Tableau 7. Renvoie

Type	Description
Flux	Objet utilisé pour interagir avec un flux d’éléments tels que des enregistrements.

Cet exemple montre comment vérifier tous les enregistrements de la table Tâche par rapport à un filtre défini. Si les enregistrements correspondent au filtre, le système renvoie le flux d’enregistrements. Dans le cas contraire, renvoie un objet Stream vide.

var shoutingTasks = new global.GlideQuery('task')
   .whereNotNull('description')
   .select('description')
   .filter(function (task) { 
       return task.description.toUpperCase() === task.description; 
   })

Flux : find(prédicat de fonction)

Renvoie le premier enregistrement ou le premier élément de l’objet Stream qui correspond à la fonction de prédicat. Si aucune fonction de prédicat n’est fournie, la méthode renvoie le premier enregistrement ou élément dans le flux.

Tableau 8. Paramètres

Nom	Type	Description
prédicat	Fonction	Facultatif. Fonction de prédicat à appliquer aux éléments à l’intérieur de l’objet Stream. La fonction doit prendre chaque élément du flux comme entrée et renvoyer un booléen.

Tableau 9. Renvoie

Type	Description
Facultatif	Objet contenant l’enregistrement renvoyé.

Cet exemple montre comment renvoyer le premier enregistrement à partir du flux.

var UserOptional = new global.GlideQuery('sys_user')
   .where('active', true)
   .where('company.name', 'ServiceNow')
   .select()
   .find()
   .map(function (user) { 
      return JSON.stringify(user); 
   })

gs.info(UserOptional);

Sortie :

Optional<{"sys_id":"babb4639b76233004fbc2089ee11a97f"}>

Flux : flatMap(function fn)

Applique une fonction à chaque élément d’un flux. Renvoie un autre flux sur lequel vous pouvez itérer.

Utilisez cette méthode au lieu de map() si la fonction renvoie un deuxième flux d’enregistrements.

Tableau 10. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à appliquer au résultat de la requête qui renvoie un objet de flux.

Tableau 11. Renvoie

Type	Description
Flux	Objet contenant le flux d’enregistrements mis à jour après l’application de la fonction.

Cet exemple vous montre comment interroger la table Utilisateur, puis créer une requête enfant à partir des résultats. Cet exemple exécute une requête N+1, ce qui peut entraîner des problèmes de performances. Évitez ce cas d’utilisation dans un environnement de production.

var records = new global.GlideQuery('sys_user')
   .where('last_login', '>', '2015-12-31')
   .select('first_name', 'last_name')
   .flatMap(function (u) {
      return new global.GlideQuery('task')
           .where('closed_by', u.sys_id)
           .select('closed_at', 'description')
           .map(function (t) {
                return {
                    first_name: u.first_name,
                    last_name: u.last_name,
                    description: t.description,
                    closed_at: t.closed_at
                 };
           });
      })
   .limit(5)
   .toArray(100);

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

Sortie :

[
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:14:56"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:07:43"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-06-15 06:59:05"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:07:33"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:07:14"
   }
]

Flux : forEach(Function fn)

Applique la fonction spécifiée à chaque enregistrement ou élément du flux.

Tableau 12. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à appliquer à chaque élément du flux.

Tableau 13. Renvoie

Type	Description
Aucun

Cet exemple vous montre comment imprimer le résultat de chaque élément du flux.

var firstNames = new global.GlideQuery('sys_user')
   .select('first_name')
   .forEach(function (u) { 
      gs.debug(u.first_name); 
   });

Sortie :

*** Script: [DEBUG] survey
*** Script: [DEBUG] Lucius
*** Script: [DEBUG] Jimmie
*** Script: [DEBUG] Melinda
*** Script: [DEBUG] Jewel
*** Script: [DEBUG] Sean
*** Script: [DEBUG] Jacinto
*** Script: [DEBUG] Krystle
*** Script: [DEBUG] Billie
*** Script: [DEBUG] Christian
*** Script: [DEBUG] Naomi
...

Flux : fromArray(Object arr)

Renvoie un objet Stream qui contient les valeurs du tableau fourni.

Remarque :

Cette méthode est statique. Vous n’avez pas besoin d’une instance de la classe pour utiliser cette méthode.

Tableau 14. Paramètres

Nom	Type	Description
Arr	Tableau	Tableau de valeurs à partir duquel créer le flux.

Tableau 15. Renvoie

Type	Description
Flux	Objet utilisé pour interagir avec un flux d’éléments tels que des enregistrements.

Cet exemple montre comment créer un objet Stream contenant un tableau de valeurs.

var nameStream = Stream.fromArray(['Bob', 'Sue', 'Sam'])
   .map(function (name) { 
      return name.toUpperCase(); 
   })
   .toArray(3);

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

Sortie :

["BOB","SUE","SAM"]

Flux : limit(nombre nombre)

Limite le nombre de résultats renvoyés par le flux.

Pour de meilleures performances, utilisez la méthode limit() dans la classe GlideQuery lorsque cela est possible. Voir GlideQuery. Vous devrez peut-être utiliser cette méthode pour limiter les résultats avec la méthode Stream.flatMap().

Tableau 16. Paramètres

Nom	Type	Description
compter	Numéro	Nombre d’enregistrements à renvoyer.

Tableau 17. Renvoie

Type	Description
Flux	Objet utilisé pour interagir avec un flux d’éléments tels que des enregistrements.

Cet exemple vous montre comment limiter les résultats renvoyés par la méthode Stream.flatMap().

var records = new global.GlideQuery('sys_user')
   .where('last_login', '>', '2015-12-31')
   .select('first_name', 'last_name')
   .flatMap(function (u) {
      return new GlideQuery('task')
           .where('closed_by', u.sys_id)
           .select('closed_at', 'description')
           .map(function (t) {
                return {
                    first_name: u.first_name,
                    last_name: u.last_name,
                    description: t.description,
                    closed_at: t.closed_at
                 };
           });
      })
   .limit(5)
   .forEach(function (task){
      gs.info(JSON.stringify(task, null, 2));
   });

Sortie :

*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:16"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:22"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:27"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:31"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:54"
}

Flux : map(Fonction fn)

Applique une fonction à chaque élément d’un flux et renvoie l’objet de flux mis à jour.

Tableau 18. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à appliquer au résultat de la requête qui prend chaque élément du flux comme entrée.

Tableau 19. Renvoie

Type	Description
Flux	Objet contenant le flux d’enregistrements mis à jour après l’application de la fonction.

Cet exemple vous montre comment appliquer une fonction à chaque élément du flux.

var users = new global.GlideQuery('sys_user')
   .whereNotNull('first_name')
   .select('first_name')
   .map(function (u) { 
      return u.first_name.toUpperCase(); 
   })
   .toArray(100);

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

Sortie :

[
   "SURVEY",
   "LUCIUS",
   "JIMMIE",
   "MELINDA",
   "JEWEL",
   "SEAN",
   "JACINTO",
   "KRYSTLE",
   "BILLIE",
   "CHRISTIAN",
   ...
]

Flux : reduce(function reducerFn, Any initialValue)

Exécute une fonction de réduction sur chaque élément du flux, ce qui permet d’obtenir une valeur de sortie unique.

Cette méthode est similaire à la méthode native JavaScript reduce(). Pour plus d’informations, consultez la documentation w3schools.

Tableau 20. Paramètres

Nom	Type	Description
réducteurFn	Fonction	Fonction à appliquer à chaque élément du flux qui réduit le flux à une seule valeur. Cette fonction doit prendre deux arguments : acc : Accumulateur qui accumule toutes les valeurs renvoyées par la fonction. cur : Élément actuel en cours d’accumulation dans le tableau.
valeur initiale	N'importe lequel	Valeur transmise à la fonction en tant que valeur initiale.

Tableau 21. Renvoie

Type	Description
N'importe lequel	Total cumulé de tous les éléments renvoyés par la fonction de réduction.

Cet exemple montre comment retourner l’enregistrement avec le nom le plus long à partir de la table Utilisateur.

var longestName = new global.GlideQuery('sys_user')
   .whereNotNull('first_name')
   .select('first_name')
   .reduce(function (acc, cur) {
       return cur.first_name.length > acc.length
           ? cur.first_name
           : acc;
       }, '');

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

Sortie :

"ATF_TestItilUser1"

Flux : some (prédicat de fonction)

Applique une fonction de prédicat, une fonction qui prend une seule valeur et renvoie vrai ou faux, à chaque élément du flux. Si le prédicat renvoie true pour n’importe quel élément du flux, la méthode retourne true.

Tableau 22. Paramètres

Nom	Type	Description
prédicat	Fonction	Fonction de prédicat à appliquer aux éléments à l’intérieur de l’objet Stream. Doit renvoyer une valeur booléenne.

Tableau 23. Renvoie

Type	Description
Booléen	Marqueur indiquant si la fonction de prédicat a retourné la valeur vrai pour un élément dans le flux. Valeurs valides : true : la fonction de prédicat a renvoyé true pour un élément dans le flux. false : la fonction de prédicat n’a pas renvoyé la valeur vrai pour un élément du flux.

Cet exemple montre comment vérifier si les descriptions de la table Tâche font plus de 1 000 caractères.

var hasLongDescriptions = new global.GlideQuery('task')
   .whereNotNull('description')
   .select('description')
   .some(function (t) { 
      return t.description.length > 1000; 
   });


gs.info(hasLongDescriptions);

Sortie :

false

Flux : toArray(Nombre de nombres)

Renvoie un tableau contenant le nombre donné d’éléments du flux.

Tableau 24. Paramètres

Nom	Type	Description
compter	Numéro	Nombre maximal d’éléments du flux à renvoyer dans le tableau.

Tableau 25. Renvoie

Type	Description
Tableau	Tableau contenant le nombre donné d’éléments du flux.

Cet exemple vous montre comment transformer un flux d’enregistrements en tableau JavaScript.

var users = new global.GlideQuery('sys_user')
    .limit(10)
    .select('first_name', 'last_name')
    .toArray(50);

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

Sortie :

[
   {
      "first_name":"Jewel",
      "last_name":"Agresta",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d64"
   },
   {
      "first_name":"Sean",
      "last_name":"Bonnet",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d6d"
   },
   {
      "first_name":"Jacinto",
      "last_name":"Gawron",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d76"
   },
   {
      "first_name":"Krystle",
      "last_name":"Stika",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d7f"
   },
   {
      "first_name":"Billie",
      "last_name":"Cowley",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d88"
   },
   {
      "first_name":"Christian",
      "last_name":"Marnell",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d91"
   }
]