[comment]: # ({e1a912b1-6537e63f}) # Funções foreach [comment]: # ({/e1a912b1-6537e63f}) [comment]: # ({d194b7c7-7d50e3a2}) ### Visão geral As funções Foreach são usadas em [cálculos agregados](/manual/config/items/itemtypes/calculated#data-aggregations) para retornar um valor agregado para cada item selecionado pelo **filtro de item** usado. Um array de valores é retornado. Por exemplo, a função `avg_foreach` retornará um array de valores, em que cada valor é o valor de histórico *médio* do item selecionado, durante o intervalo de tempo especificado. ::: noteimportant As funções Foreach são suportadas apenas em fórmulas de [item calculado](/manual/config/items/itemtypes/calculated). Elas não podem ser invocadas em chaves de item simples nem usadas diretamente para construir expressões de trigger. Em expressões de trigger, um item calculado pode ser usado referenciando sua chave. ::: O [filtro de item](#item-filter-syntax) faz parte da sintaxe usada pelas funções foreach. O uso de curingas é समर्थado no filtro de item, portanto os itens necessários podem ser selecionados de forma bastante flexível. [comment]: # ({/d194b7c7-7d50e3a2}) [comment]: # ({2afbf13f-c9e1960d}) ### Funções suportadas |Function|Description| |--|--------| |*avg_foreach*|Retorna o valor médio para cada item.| |*bucket_rate_foreach*|Retorna pares (limite superior do bucket, valor da taxa) adequados para uso na função [`histogram_quantile()`](/manual/config/triggers/expression/aggregate#histogram-quantile), em que "limite superior do bucket" é o valor do parâmetro da chave do item definido pelo [parâmetro](#additional-parameters) .| |*count_foreach*|Retorna o número de valores para cada item.| |*exists_foreach*|Retorna '1' para cada item habilitado.| |*last_foreach*|Retorna o último valor para cada item.| |*max_foreach*|Retorna o valor máximo para cada item.| |*min_foreach*|Retorna o valor mínimo para cada item.| |*sum_foreach*|Retorna a soma dos valores para cada item.| [comment]: # ({/2afbf13f-c9e1960d}) [comment]: # ({a8e9955e-2cf639a9}) ### Sintaxe da função As funções foreach suportam dois parâmetros comuns: `filtro de item` (veja os detalhes abaixo) e `período de tempo`: foreach_function(item filter,time period) Por exemplo: `avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)` retornará a média de cinco minutos de cada item 'mysql.qps' no grupo de servidores MySQL. Observe que algumas funções suportam [parâmetros](#additional-parameters) adicionais. [comment]: # ({/a8e9955e-2cf639a9}) [comment]: # ({f8b1fa52-737d2e38}) #### Sintaxe do filtro de item O filtro de item: /host/key[parameters]?[conditions] consiste em quatro partes, onde: * host - nome do host * key - chave do item (sem parâmetros) * parameters - parâmetros da chave do item * conditions - condições baseadas em grupo de host e/ou tag de item (como expressão) Espaços são permitidos apenas dentro da expressão de condições. **Uso de curinga** * O curinga pode ser usado para substituir o nome do host, a chave do item ou um parâmetro individual da chave do item. * Ou o host ou a chave do item devem ser especificados sem curinga. Portanto, `/host/*` e `/*/key` são filtros válidos, mas `/*/*` é inválido. * O curinga não pode ser usado para *parte* do nome do host, chave do item ou parâmetro da chave do item. * O curinga não corresponde a mais de um parâmetro da chave do item. Portanto, um curinga deve ser especificado para cada parâmetro separadamente (ou seja, `key[abc,*,*]`). **Expressão de condições** A expressão de condições suporta: * operandos: * group - grupo de host * tag - tag do item * `""` - constante de string, com o caractere de escape `\` para escapar `"` e `\` * operadores de comparação de string sensíveis a maiúsculas e minúsculas: `=`, `<>` * operadores lógicos: `and`, `or`, `not` * agrupamento com parênteses: `(` `)` A citação de constantes de string é obrigatória. Apenas a comparação de string completa e sensível a maiúsculas e minúsculas é suportada. :::notewarning Ao especificar tags no filtro (ou seja, `tag="tagname:value"`), o dois-pontos ":" é usado como delimitador. Tudo após ele é considerado o valor da tag. Portanto, atualmente não é suportado especificar um nome de tag contendo ":". ::: **Exemplos** Um filtro complexo pode ser usado, referenciando a chave do item, grupo de host e tags, conforme ilustrado pelos exemplos: |Exemplo de sintaxe|Descrição| |--|--| |`/host/key[abc,*]`|Corresponde a itens semelhantes neste host.| |`/*/key`|Corresponde ao mesmo item de qualquer host.| |`/*/key?[group="ABC" and tag="tagname:value"]`|Corresponde ao mesmo item de qualquer host do grupo ABC que tenha tags 'tagname:value'.| |`/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`|Corresponde a itens semelhantes de qualquer host do grupo ABC ou DEF com as respectivas tags.| Todos os itens referenciados devem existir e coletar dados. Apenas itens habilitados em hosts habilitados são incluídos nos cálculos. Itens em estado não suportado não são incluídos. ::: noteimportant Se a chave do item de um item referenciado for alterada, o filtro deverá ser atualizado manualmente. ::: Especificar um grupo de host pai inclui o grupo pai e todos os grupos de host aninhados com seus itens. [comment]: # ({/f8b1fa52-737d2e38}) [comment]: # ({2ab7aef7-0a9b9b28}) #### Período de tempo O **segundo** parâmetro permite especificar o período de tempo para agregação. O período de tempo só pode ser expresso como tempo, a quantidade de valores (prefixada com **\#**) não é suportada. [Unidades de tempo suportadas](/manual/appendix/suffixes) podem ser usadas neste parâmetro para conveniência, por exemplo, '5m' (cinco minutos) em vez de '300s' (300 segundos) ou '1d' (um dia) em vez de '86400' (86400 segundos). Para a função *last\_foreach*, o período de tempo é um parâmetro opcional (suportado desde o Zabbix 7.0), que pode ser omitido: last_foreach(/*/key?[group="host group"]) O período de tempo não é suportado com a função *exists\_foreach*. [comment]: # ({/2ab7aef7-0a9b9b28}) [comment]: # ({a4d91525-bf880e22}) #### Parâmetros adicionais **bucket\_rate\_foreach** Um terceiro parâmetro opcional é suportado pela função *bucket\_rate\_foreach*: bucket_rate_foreach(item filter,time period,) onde é a posição do valor "bucket" na chave do item. Por exemplo, se o valor "bucket" em myItem\[aaa,0.2\] for '0.2', então sua posição é 2. O valor padrão de é '1'. **count\_foreach** O terceiro e o quarto parâmetros opcionais são suportados pela função *count\_foreach*: count_foreach(item filter,time period,,) Onde: - **operator** é o operador condicional para valores de item (deve estar entre aspas duplas). `operators` suportados:
*eq* - igual
*ne* - diferente
*gt* - maior
*ge* - maior ou igual
*lt* - menor
*le* - menor ou igual
*like* - corresponde se contiver o padrão (diferencia maiúsculas de minúsculas)
*bitand* - AND bit a bit
*regexp* - correspondência sensível a maiúsculas e minúsculas da expressão regular fornecida em `pattern`
*iregexp* - correspondência insensível a maiúsculas e minúsculas da expressão regular fornecida em `pattern`
- **pattern** é o padrão obrigatório (argumentos de string devem estar entre aspas duplas); suportado se *operator* for especificado no terceiro parâmetro. Comentários: - Os parâmetros opcionais *operator* ou *pattern* não podem ser deixados vazios após uma vírgula, apenas totalmente omitidos. - Com *bitand* como terceiro parâmetro, o quarto parâmetro `pattern` pode ser especificado como dois números, separados por '/': **number_to_compare_with/mask**. count\_foreach() calcula o "AND bit a bit" do valor e da *mask* e compara o resultado com *number_to_compare_with*. Se o resultado do "AND bit a bit" for igual a *number_to_compare_with*, o valor será contado.
Se *number_to_compare_with* e *mask* forem iguais, apenas a *mask* precisa ser especificada (sem '/'). - Com *regexp* ou *iregexp* como terceiro parâmetro, o quarto parâmetro `pattern` pode ser uma expressão regular comum ou [global](/manual/regular_expressions#global-regular-expressions) (iniciando com '@'). No caso de expressões regulares globais, a diferenciação entre maiúsculas e minúsculas é herdada das configurações da expressão regular global. Para fins de correspondência regexp, valores float sempre serão representados com 4 dígitos decimais após '.'. Observe também que, para números grandes, a diferença entre a representação decimal (armazenada no banco de dados) e binária (usada pelo Zabbix server) pode afetar o 4º dígito decimal. Consulte [cálculos agregados](/manual/config/items/itemtypes/calculated/aggregate) para mais detalhes e exemplos de uso das funções foreach. [comment]: # ({/a4d91525-bf880e22}) [comment]: # ({fc23e115-328844f6}) #### Comportamento dependendo da disponibilidade A tabela a seguir ilustra como cada função se comporta em casos de disponibilidade limitada do host/item e dos dados históricos. |Função|Host desabilitado|Host indisponível com dados|Host indisponível sem dados|Item desabilitado|Item não suportado|Erro de recuperação de dados (SQL)| |--|--|--|--|--|--|--| |*avg_foreach*|ignorar|retornar média|ignorar|ignorar|ignorar|ignorar| |*bucket_rate_foreach*|ignorar|retornar bucket rate|ignorar|ignorar|ignorar|ignorar| |*count_foreach*|ignorar|retornar contagem|0|ignorar|ignorar|ignorar| |*exists_foreach*|ignorar|1|1|ignorar|1|n/a| |*last_foreach*|ignorar|retornar último|ignorar|ignorar|ignorar|ignorar| |*max_foreach*|ignorar|retornar máximo|ignorar|ignorar|ignorar|ignorar| |*min_foreach*|ignorar|retornar mínimo|ignorar|ignorar|ignorar|ignorar| |*sum_foreach*|ignorar|retornar soma|ignorar|ignorar|ignorar|ignorar| Se o item for *ignorado*, nada é adicionado à agregação. [comment]: # ({/fc23e115-328844f6})