[comment]: # ({e1a912b1-6537e63f}) # Fonctions foreach [comment]: # ({/e1a912b1-6537e63f}) [comment]: # ({80f2858e-7d50e3a2}) ### Aperçu Les fonctions foreach sont utilisées dans les [calculs agrégés](/manual/config/items/itemtypes/calculated#data-aggregations) pour renvoyer une valeur agrégée pour chaque élément sélectionné par le **filtre d'élément** utilisé. Un tableau de valeurs est renvoyé. Par exemple, la fonction *avg_foreach* renverra un tableau de valeurs, où chaque valeur correspond à la valeur d'historique *moyenne* de l'élément sélectionné, pendant l'intervalle de temps spécifié. ::: noteimportant Les fonctions foreach sont prises en charge uniquement dans les formules d'[élément calculé](/manual/config/items/itemtypes/calculated). Elles ne peuvent pas être appelées dans des clés d'élément simples ni utilisées directement pour construire des expressions de déclencheur. Dans les expressions de déclencheur, un élément calculé peut être utilisé en référençant sa clé. ::: Le [filtre d'élément](#item-filter-syntax) fait partie de la syntaxe utilisée par les fonctions foreach. L'utilisation de caractères génériques est prise en charge dans le filtre d'élément, ce qui permet de sélectionner les éléments requis de manière très flexible. [comment]: # ({/80f2858e-7d50e3a2}) [comment]: # ({85037981-c9e1960d}) ### Fonctions prises en charge |Fonction|Description| |--|--------| |*avg_foreach*|Renvoie la valeur moyenne pour chaque élément.| |*bucket_rate_foreach*|Renvoie des paires (limite supérieure du compartiment, valeur du taux) pouvant être utilisées dans la fonction [histogram\_quantile()](/manual/config/triggers/expression/aggregate#histogram-quantile), où la « limite supérieure du compartiment » est la valeur du paramètre de clé d'élément défini par le [paramètre](#additional-parameters) .| |*count_foreach*|Renvoie le nombre de valeurs pour chaque élément.| |*exists_foreach*|Renvoie « 1 » pour chaque élément activé.| |*last_foreach*|Renvoie la dernière valeur pour chaque élément.| |*max_foreach*|Renvoie la valeur maximale pour chaque élément.| |*min_foreach*|Renvoie la valeur minimale pour chaque élément.| |*sum_foreach*|Renvoie la somme des valeurs pour chaque élément.| [comment]: # ({/85037981-c9e1960d}) [comment]: # ({f0e3ac5a-2cf639a9}) ### Syntaxe des fonctions Les fonctions foreach prennent en charge deux paramètres communs : `filtre d’élément` (voir les détails ci-dessous) et `période de temps` : foreach_function(item filter,time period) Par exemple : `avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)` renverra la moyenne sur cinq minutes de chaque élément 'mysql.qps' dans le groupe de serveurs MySQL. Notez que certaines fonctions prennent en charge des [paramètres](#additional-parameters) supplémentaires. [comment]: # ({/f0e3ac5a-2cf639a9}) [comment]: # ({b34ce1e4-737d2e38}) #### Syntaxe du filtre d’élément Le filtre d’élément : /host/key[parameters]?[conditions] se compose de quatre parties, où : * host - nom d’hôte * key - clé d’élément (sans paramètres) * parameters - paramètres de la clé d’élément * conditions - conditions basées sur le groupe d’hôtes et/ou les tags d’élément (sous forme d’expression) Les espaces sont autorisés uniquement à l’intérieur de l’expression de conditions. **Utilisation des caractères génériques** * Un caractère générique peut être utilisé pour remplacer le nom d’hôte, la clé d’élément ou un paramètre individuel de la clé d’élément. * Soit l’hôte, soit la clé d’élément doit être spécifié sans caractère générique. Ainsi, `/host/*` et `/*/key` sont des filtres valides, mais `/*/*` est invalide. * Un caractère générique ne peut pas être utilisé pour une *partie* du nom d’hôte, de la clé d’élément ou d’un paramètre de clé d’élément. * Un caractère générique ne correspond pas à plus d’un seul paramètre de clé d’élément. Ainsi, un caractère générique doit être spécifié séparément pour chaque paramètre (c’est-à-dire `key[abc,*,*]`). **Expression de conditions** L’expression de conditions prend en charge : * opérandes : * group - groupe d’hôtes * tag - tag d’élément * `""` - constante de chaîne, avec le caractère d’échappement `\` pour échapper `"` et `\` * opérateurs de comparaison de chaînes sensibles à la casse : `=`, `<>` * opérateurs logiques : `and`, `or`, `not` * regroupement avec parenthèses : `(` `)` La mise entre guillemets des constantes de chaîne est obligatoire. Seule la comparaison complète de chaînes sensible à la casse est prise en charge. :::notewarning Lors de la spécification des tags dans le filtre (c’est-à-dire `tag="tagname:value"`), le deux-points ":" est utilisé comme délimiteur. Tout ce qui suit est considéré comme la valeur du tag. Ainsi, il n’est actuellement pas possible de spécifier un nom de tag contenant ":". ::: **Exemples** Un filtre complexe peut être utilisé, en faisant référence à la clé d’élément, au groupe d’hôtes et aux tags, comme l’illustrent les exemples : |Exemple de syntaxe|Description| |--|--| |`/host/key[abc,*]`|Correspond à des éléments similaires sur cet hôte.| |`/*/key`|Correspond au même élément de n’importe quel hôte.| |`/*/key?[group="ABC" and tag="tagname:value"]`|Correspond au même élément de n’importe quel hôte du groupe ABC ayant les tags 'tagname:value'.| |`/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`|Correspond à des éléments similaires de n’importe quel hôte du groupe ABC ou DEF avec les tags respectifs.| Tous les éléments référencés doivent exister et collecter des données. Seuls les éléments activés sur des hôtes activés sont inclus dans les calculs. Les éléments dans l’état non pris en charge ne sont pas inclus. ::: noteimportant Si la clé d’élément d’un élément référencé est modifiée, le filtre doit être mis à jour manuellement. ::: La spécification d’un groupe d’hôtes parent inclut le groupe parent et tous les groupes d’hôtes imbriqués avec leurs éléments. [comment]: # ({/b34ce1e4-737d2e38}) [comment]: # ({a5305339-0a9b9b28}) #### Période de temps Le **deuxième** paramètre permet de spécifier la période de temps pour l’agrégation. La période de temps ne peut être exprimée qu’en durée ; le nombre de valeurs (préfixé par **\#**) n’est pas pris en charge. Les [symboles d’unité pris en charge](/manual/appendix/suffixes) peuvent être utilisés dans ce paramètre pour plus de commodité, par exemple, « 5m » (cinq minutes) au lieu de « 300s » (300 secondes) ou « 1d » (un jour) au lieu de « 86400 » (86400 secondes). Pour la fonction *last\_foreach*, la période de temps est un paramètre facultatif (pris en charge depuis Zabbix 7.0), qui peut être omis : last_foreach(/*/key?[group="host group"]) La période de temps n’est pas prise en charge avec la fonction *exists\_foreach*. [comment]: # ({/a5305339-0a9b9b28}) [comment]: # ({d143a2b5-bf880e22}) #### Paramètres supplémentaires **bucket\_rate\_foreach** Un troisième paramètre facultatif est pris en charge par la fonction *bucket\_rate\_foreach* : bucket_rate_foreach(item filter,time period,) où est la position de la valeur « bucket » dans la clé de l’élément. Par exemple, si la valeur « bucket » dans myItem\[aaa,0.2\] est « 0.2 », alors sa position est 2. La valeur par défaut de est « 1 ». **count\_foreach** Les troisième et quatrième paramètres facultatifs sont pris en charge par la fonction *count\_foreach* : count_foreach(item filter,time period,,) Où : - **operator** est l’opérateur conditionnel pour les valeurs d’élément (doit être entre guillemets doubles). `operators` pris en charge :
*eq* - égal
*ne* - différent
*gt* - supérieur
*ge* - supérieur ou égal
*lt* - inférieur
*le* - inférieur ou égal
*like* - correspond si contient le motif (sensible à la casse)
*bitand* - ET binaire
*regexp* - correspondance sensible à la casse de l’expression régulière fournie dans `pattern`
*iregexp* - correspondance insensible à la casse de l’expression régulière fournie dans `pattern`
- **pattern** est le motif requis (les arguments de chaîne doivent être entre guillemets doubles) ; pris en charge si *operator* est spécifié dans le troisième paramètre. Commentaires : - Les paramètres facultatifs *operator* ou *pattern* ne peuvent pas être laissés vides après une virgule ; ils peuvent uniquement être totalement omis. - Avec *bitand* comme troisième paramètre, le quatrième paramètre `pattern` peut être spécifié sous forme de deux nombres, séparés par « / » : **number_to_compare_with/mask**. count\_foreach() calcule un « ET binaire » à partir de la valeur et du *mask* et compare le résultat à *number_to_compare_with*. Si le résultat du « ET binaire » est égal à *number_to_compare_with*, la valeur est comptée.
Si *number_to_compare_with* et *mask* sont égaux, seul le *mask* doit être spécifié (sans « / »). - Avec *regexp* ou *iregexp* comme troisième paramètre, le quatrième paramètre `pattern` peut être une expression régulière ordinaire ou [globale](/manual/regular_expressions#global-regular-expressions) (commençant par « @ »). Dans le cas des expressions régulières globales, la sensibilité à la casse est héritée des paramètres des expressions régulières globales. Aux fins de la correspondance regexp, les valeurs flottantes seront toujours représentées avec 4 chiffres décimaux après « . ». Notez également que, pour les grands nombres, la différence entre la représentation décimale (stockée dans la base de données) et binaire (utilisée par le serveur Zabbix) peut affecter le 4e chiffre décimal. Voir [calculs agrégés](/manual/config/items/itemtypes/calculated/aggregate) pour plus de détails et d’exemples sur l’utilisation des fonctions foreach. [comment]: # ({/d143a2b5-bf880e22}) [comment]: # ({fc23e115-328844f6}) #### Comportement en fonction de la disponibilité Le tableau suivant illustre le comportement de chaque fonction en cas de disponibilité limitée de l'hôte/de l'élément et des données d'historique. |Function|Disabled host|Unavailable host with data|Unavailable host without data|Disabled item|Unsupported item|Data retrieval error (SQL)| |--|--|--|--|--|--|--| |*avg_foreach*|ignorer|retourner la moyenne|ignorer|ignorer|ignorer|ignorer| |*bucket_rate_foreach*|ignorer|retourner le taux du compartiment|ignorer|ignorer|ignorer|ignorer| |*count_foreach*|ignorer|retourner le nombre|0|ignorer|ignorer|ignorer| |*exists_foreach*|ignorer|1|1|ignorer|1|n/a| |*last_foreach*|ignorer|retourner la dernière valeur|ignorer|ignorer|ignorer|ignorer| |*max_foreach*|ignorer|retourner le maximum|ignorer|ignorer|ignorer|ignorer| |*min_foreach*|ignorer|retourner le minimum|ignorer|ignorer|ignorer|ignorer| |*sum_foreach*|ignorer|retourner la somme|ignorer|ignorer|ignorer|ignorer| Si l'élément est *ignoré*, rien n'est ajouté à l'agrégation. [comment]: # ({/fc23e115-328844f6})