[comment]: # ({6537e63f-6537e63f}) # 1 Funzioni foreach [comment]: # ({/6537e63f-6537e63f}) [comment]: # ({5f3bebe2-7d50e3a2}) ### Panoramica Le funzioni Foreach vengono utilizzate nei [calcoli aggregati](/manual/config/items/itemtypes/calculated/aggregate) per restituire un valore aggregato per ogni item selezionato dal **filtro item** utilizzato. Viene restituito un array di valori. ::: noteimportant Le funzioni Foreach sono supportate solo all'interno degli [item calcolati](/manual/config/items/itemtypes/calculated) come parte delle formule di calcolo aggregato. Non possono essere invocate in semplici chiavi item o espressioni trigger al di fuori di questo contesto. ::: Ad esempio, la funzione `avg_foreach` restituirà un array di valori, in cui ogni valore è il valore storico *medio* dell'item selezionato, durante l'intervallo di tempo specificato. Il [filtro item](#item-filter-syntax) fa parte della sintassi utilizzata dalle funzioni foreach. L'uso dei caratteri jolly è supportato nel filtro item, quindi gli item richiesti possono essere selezionati in modo molto flessibile. [comment]: # ({/5f3bebe2-7d50e3a2}) [comment]: # ({1e055e7c-c9e1960d}) ### Funzioni supportate |Function|Description| |--|--------| |*avg_foreach*|Restituisce il valore medio per ciascun item.| |*bucket_rate_foreach*|Restituisce coppie (limite superiore del bucket, valore del rate) adatte all'uso nella funzione [histogram\_quantile()](/manual/appendix/functions/aggregate#histogram-quantile), dove "limite superiore del bucket" è il valore del parametro della chiave dell'item definito dal [parametro](#additional-parameters) .| |*count_foreach*|Restituisce il numero di valori per ciascun item.| |*exists_foreach*|Restituisce '1' per ciascun item abilitato.| |*last_foreach*|Restituisce l'ultimo valore per ciascun item.| |*max_foreach*|Restituisce il valore massimo per ciascun item.| |*min_foreach*|Restituisce il valore minimo per ciascun item.| |*sum_foreach*|Restituisce la somma dei valori per ciascun item.| [comment]: # ({/1e055e7c-c9e1960d}) [comment]: # ({a8e9955e-2cf639a9}) ### Sintassi della funzione Le funzioni foreach supportano due parametri comuni: `filtro item` (vedi i dettagli sotto) e `periodo di tempo`: foreach_function(item filter,time period) Per esempio: `avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)` restituirà la media su cinque minuti di ciascun item 'mysql.qps' nel gruppo di server MySQL. Si noti che alcune funzioni supportano [parametri](#additional-parameters) aggiuntivi. [comment]: # ({/a8e9955e-2cf639a9}) [comment]: # ({f8b1fa52-737d2e38}) #### Sintassi del filtro item Il filtro item: /host/key[parameters]?[conditions] è composto da quattro parti, dove: * host - nome del host * key - chiave dell'item (senza parametri) * parameters - parametri della chiave dell'item * conditions - condizioni basate sul gruppo host e/o sui tag dell'item (come espressione) Gli spazi sono consentiti solo all'interno dell'espressione delle condizioni. **Uso dei caratteri jolly** * Il carattere jolly può essere utilizzato per sostituire il nome del host, la chiave dell'item o un singolo parametro della chiave dell'item. * Il host oppure la chiave dell'item deve essere specificato senza carattere jolly. Quindi `/host/*` e `/*/key` sono filtri validi, ma `/*/*` non è valido. * Il carattere jolly non può essere utilizzato per una *parte* del nome del host, della chiave dell'item o del parametro della chiave dell'item. * Il carattere jolly non corrisponde a più di un singolo parametro della chiave dell'item. Pertanto, deve essere specificato un carattere jolly per ciascun parametro separatamente (ad esempio `key[abc,*,*]`). **Espressione delle condizioni** L'espressione delle condizioni supporta: * operandi: * group - gruppo host * tag - tag dell'item * `""` - costante stringa, con il carattere di escape `\` per eseguire l'escape di `"` e `\` * operatori di confronto tra stringhe con distinzione tra maiuscole e minuscole: `=`, `<>` * operatori logici: `and`, `or`, `not` * raggruppamento con parentesi: `(` `)` Le virgolette per le costanti stringa sono obbligatorie. È supportato solo il confronto completo tra stringhe con distinzione tra maiuscole e minuscole. :::notewarning Quando si specificano i tag nel filtro (ad esempio `tag="tagname:value"`), i due punti ":" vengono utilizzati come delimitatore. Tutto ciò che segue viene considerato il valore del tag. Pertanto, attualmente non è supportato specificare un nome tag che contenga ":". ::: **Esempi** Può essere utilizzato un filtro complesso che fa riferimento alla chiave dell'item, al gruppo host e ai tag, come illustrato negli esempi: |Syntax example|Description| |--|--| |`/host/key[abc,*]`|Corrisponde a item simili su questo host.| |`/*/key`|Corrisponde allo stesso item di qualsiasi host.| |`/*/key?[group="ABC" and tag="tagname:value"]`|Corrisponde allo stesso item di qualsiasi host del gruppo ABC che abbia tag 'tagname:value'.| |`/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`|Corrisponde a item simili di qualsiasi host del gruppo ABC o DEF con i rispettivi tag.| Tutti gli item referenziati devono esistere e raccogliere dati. Solo gli item abilitati su host abilitati sono inclusi nei calcoli. Gli item nello stato unsupported non sono inclusi. ::: noteimportant Se la chiave dell'item di un item referenziato viene modificata, il filtro deve essere aggiornato manualmente. ::: La specifica di un gruppo host padre include il gruppo padre e tutti i gruppi host nidificati con i relativi item. [comment]: # ({/f8b1fa52-737d2e38}) [comment]: # ({2ab7aef7-0a9b9b28}) #### Periodo di tempo Il secondo parametro consente di specificare il periodo di tempo per l'aggregazione. Il periodo di tempo può essere espresso solo come tempo; la quantità di valori (preceduta da **\#**) non è supportata. In questo parametro, per comodità, è possibile utilizzare i [simboli di unità supportati](/manual/appendix/suffixes), ad esempio '5m' (cinque minuti) invece di '300s' (300 secondi) oppure '1d' (un giorno) invece di '86400' (86400 secondi). Per la funzione *last\_foreach*, il periodo di tempo è un parametro facoltativo (supportato da Zabbix 7.0), che può essere omesso: last_foreach(/*/key?[group="host group"]) Il periodo di tempo non è supportato con la funzione *exists\_foreach*. [comment]: # ({/2ab7aef7-0a9b9b28}) [comment]: # ({a4d91525-bf880e22}) #### Parametri aggiuntivi **bucket\_rate\_foreach** Un terzo parametro opzionale è supportato dalla funzione *bucket\_rate\_foreach*: bucket_rate_foreach(item filter,time period,) dove è la posizione del valore "bucket" nella chiave item. Ad esempio, se il valore "bucket" in myItem\[aaa,0.2\] è '0.2', allora la sua posizione è 2. Il valore predefinito di è '1'. **count\_foreach** La funzione *count\_foreach* supporta un terzo e un quarto parametro opzionale: count_foreach(item filter,time period,,) Dove: - **operator** è l'operatore condizionale per i valori item (deve essere racchiuso tra doppi apici). `operatori` supportati:
*eq* - uguale
*ne* - diverso
*gt* - maggiore
*ge* - maggiore o uguale
*lt* - minore
*le* - minore o uguale
*like* - corrisponde se contiene il pattern (con distinzione tra maiuscole e minuscole)
*bitand* - AND bit a bit
*regexp* - corrispondenza con distinzione tra maiuscole e minuscole dell'espressione regolare fornita in `pattern`
*iregexp* - corrispondenza senza distinzione tra maiuscole e minuscole dell'espressione regolare fornita in `pattern`
- **pattern** è il pattern richiesto (gli argomenti stringa devono essere racchiusi tra doppi apici); supportato se *operator* è specificato nel terzo parametro. Commenti: - I parametri opzionali *operator* o *pattern* non possono essere lasciati vuoti dopo una virgola, ma solo omessi completamente. - Con *bitand* come terzo parametro, il quarto parametro `pattern` può essere specificato come due numeri, separati da '/': **numero_con_cui_confrontare/mask**. count\_foreach() calcola l'"AND bit a bit" dal valore e dalla *mask* e confronta il risultato con *numero_con_cui_confrontare*. Se il risultato dell'"AND bit a bit" è uguale a *numero_con_cui_confrontare*, il valore viene conteggiato.
Se *numero_con_cui_confrontare* e *mask* sono uguali, è necessario specificare solo la *mask* (senza '/'). - Con *regexp* o *iregexp* come terzo parametro, il quarto parametro `pattern` può essere un'espressione regolare ordinaria o [globale](/manual/regular_expressions#global-regular-expressions) (che inizia con '@'). Nel caso delle espressioni regolari globali, la distinzione tra maiuscole e minuscole viene ereditata dalle impostazioni dell'espressione regolare globale. Ai fini della corrispondenza regexp, i valori float saranno sempre rappresentati con 4 cifre decimali dopo '.'. Si noti inoltre che, per numeri grandi, la differenza tra la rappresentazione decimale (memorizzata nel database) e quella binaria (utilizzata dal server Zabbix) può influire sulla quarta cifra decimale. Per maggiori dettagli ed esempi sull'uso delle funzioni foreach, vedere [calcoli aggregati](/manual/config/items/itemtypes/calculated/aggregate). [comment]: # ({/a4d91525-bf880e22}) [comment]: # ({fc23e115-328844f6}) #### Comportamento in base alla disponibilità La tabella seguente illustra come si comporta ciascuna funzione nei casi di disponibilità limitata di host/item e dei dati di storico. |Function|Host disabilitato|Host non disponibile con dati|Host non disponibile senza dati|Item disabilitato|Item non supportato|Errore di recupero dati (SQL)| |--|--|--|--|--|--|--| |*avg_foreach*|ignora|restituisce avg|ignora|ignora|ignora|ignora| |*bucket_rate_foreach*|ignora|restituisce bucket rate|ignora|ignora|ignora|ignora| |*count_foreach*|ignora|restituisce count|0|ignora|ignora|ignora| |*exists_foreach*|ignora|1|1|ignora|1|n/d| |*last_foreach*|ignora|restituisce last|ignora|ignora|ignora|ignora| |*max_foreach*|ignora|restituisce max|ignora|ignora|ignora|ignora| |*min_foreach*|ignora|restituisce min|ignora|ignora|ignora|ignora| |*sum_foreach*|ignora|restituisce sum|ignora|ignora|ignora|ignora| Se l'item viene *ignorato*, non viene aggiunto nulla all'aggregazione. [comment]: # ({/fc23e115-328844f6})