1 Funções de macro

Visão geral

As funções de macro oferecem a capacidade de personalizar os valores das macros (por exemplo, encurtar ou extrair substrings específicas), tornando-os mais fáceis de trabalhar.

A sintaxe de uma função de macro é:

{macro.func(params)}

onde

• macro - a macro a ser personalizada;
• func - a função a ser aplicada (veja funções suportadas);
• params - uma lista de parâmetros da função separados por vírgula, que devem ser entre aspas duplas se:
  • começar com um espaço ou aspas duplas;
  • conter parênteses de fechamento ou uma vírgula.

Por exemplo:

{{TIME}.fmttime(format,time_shift)}
{{ITEM.VALUE}.regsub(pattern, output)}
{{$USERMACRO}.regsub(pattern, output)}
{{#LLDMACRO}.regsub(pattern, output)}

As funções de macro são suportadas para

• Macros internas
• Macros de usuário
• Macros de descoberta de baixo nível
• Macros de expressão

As funções de macro podem ser usadas em todos os locais que suportam as macros listadas. Isso se aplica, a menos que seja explicitamente declarado que apenas uma macro é esperada (por exemplo, ao configurar macros de host ou filtros de regras de descoberta de baixo nível).

É suportada uma única função por macro; múltiplas funções de macro em cadeia não são suportadas.

Funções suportadas

As funções são listadas sem informações adicionais. Clique na função para ver os detalhes completos.

Detalhes da função

Os parâmetros opcionais da função são indicados por < >.

btoa

Codifica um valor de macro em Base64. A codificação Base64 é um método para representar dados binários como texto, útil para armazenar e transmitir com segurança conteúdo binário por protocolos baseados em texto.

Exemplo:

{{ITEM.VALUE}.btoa()} - codificará em Base64 um valor como "zabbix" em "emFiYml4"

fmtnum(digits)

Formatação de número para controlar o número de dígitos impressos após o ponto decimal.

Parâmetros:

• digits - o número de dígitos após o ponto decimal. Intervalo válido: 0-20. Zeros à direita não serão produzidos.

Exemplos:

{{ITEM.VALUE}.fmtnum(2)} - retornará "24.35" a partir de um valor recebido de "24.3483523"
{{ITEM.VALUE}.fmtnum(0)} - retornará "24" a partir de um valor recebido de "24.3483523"

fmttime(format,<time_shift>)

Formatação de hora.
Observe que esta função pode ser usada com macros que resultam em um valor em um dos seguintes formatos de hora:

• hh:mm:ss
• yyyy-mm-ddThh:mm:ss[tz] (padrão ISO8601)
• timestamp UNIX

Parâmetros:

• format - string de formato obrigatória, compatível com a formatação da função strftime;
• time_shift (opcional) - o deslocamento de tempo aplicado ao horário antes da formatação; deve começar com -<N><time_unit> ou +<N><time_unit>, onde:
  • N - o número de unidades de tempo a adicionar ou subtrair;
  • time_unit - h (hora), d (dia), w (semana), M (mês) ou y (ano).

Comentários:

• O parâmetro time_shift suporta operações de tempo em múltiplos passos e pode incluir /<time_unit> para deslocar para o início da unidade de tempo (/d - meia-noite, /w - 1º dia da semana (segunda-feira), /M - 1º dia do mês, etc.). Exemplos: -1w - exatamente 7 dias atrás; -1w/w - segunda-feira da semana anterior; -1w/w+1d - terça-feira da semana anterior.
• As operações de tempo são calculadas da esquerda para a direita sem prioridades. Por exemplo, -1M/d+1h/w será interpretado como ((-1M/d)+1h)/w.

Exemplos:

{{TIME}.fmttime(%B)} - retornará "outubro" a partir de um valor recebido de "1633098961"
{{TIME}.fmttime(%d %B,-1M/M)} - retornará "1 setembro" a partir de um valor recebido de "1633098961"

htmldecode

Decodifica um valor de macro de uma codificação HTML.

Os seguintes caracteres são suportados:

Exemplo:

{{ITEM.VALUE}.htmldecode()} - irá decodificar HTML de um valor como "&lt;" para "<"

htmlencode

Codifica um valor de macro em codificação HTML.

Os seguintes caracteres são suportados:

Exemplo:

{{ITEM.VALUE}.htmlencode()} - irá codificar em HTML um caractere como "<" em "&lt;"

iregsub(pattern,output)

Extração de substring por correspondência de expressão regular (case-insensitive).

Parâmetros:

• pattern - a expressão regular a ser correspondida;
• output - as opções de saída. Os placeholders \1 - \9 são suportados para capturar grupos. \0 retorna o texto correspondente.

Comentários:

• Se não houver correspondência para a expressão regular, a função retorna uma string vazia.
• Se o padrão da função for uma expressão regular incorreta, a macro será avaliada como 'UNKNOWN' (exceto para macros de descoberta de baixo nível, caso em que a função será ignorada e a macro permanecerá não resolvida).
• Referências a grupos de captura inexistentes na string de substituição são substituídas por uma string vazia.

Exemplo:

{{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} - será resolvido como "ERROR" se as substrings "fail", "error", "fault" ou "problem" forem recebidas (case-insensitive); retornará uma string vazia se não houver correspondência

lowercase

Transformação de todos os caracteres do valor da macro em minúsculas. Funciona com conjuntos de caracteres de byte único (como ASCII) e não suporta UTF-8.

Exemplo:

{{ITEM.VALUE}.lowercase()} - irá transformar um valor como "Zabbix SERVER" em "zabbix server" (minúsculo)

regrepl(pattern,replacement,<pattern2>,<replacement2>,...)

Substituição de caractere/substring no valor da macro.

Parâmetros:

• pattern - a expressão regular a ser correspondida;
• replacement - a string de substituição. Os placeholders \1 - \9 são suportados em strings de substituição para capturar grupos.

Comentários:

• Os padrões e substituições são processados sequencialmente, com cada par subsequente sendo aplicado de acordo com o resultado da substituição anterior;
• Referências a grupos de captura inexistentes na string de substituição são substituídas por uma string vazia.

Exemplos:

{{ITEM.VALUE}.regrepl("oldParam", "newParam")} - irá substituir "oldParam" por "newParam"
{{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - todos os caracteres que não são letras serão escapados com uma barra invertida
{$THRESHOLD:"{{#FSNAME}.regrepl(\"\\$\",\"\")}"} - irá remover uma barra invertida no final (por exemplo, para substituir "C:\" por "C:")
{{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - irá substituir várias partes no valor do item

regsub(pattern,output)

Extração de substring por correspondência de expressão regular (diferencia maiúsculas de minúsculas).

Parâmetros:

• pattern - a expressão regular a ser correspondida;
• output - as opções de saída. Os placeholders \1 - \9 são suportados para capturar grupos. \0 retorna o texto correspondente.

Comentários:

• Se não houver correspondência para a expressão regular, a função retorna uma string vazia.
• Se o padrão da função for uma expressão regular incorreta, a macro será avaliada como 'UNKNOWN' (exceto para macros de descoberta de baixo nível, caso em que a função será ignorada e a macro permanecerá não resolvida).
• Referências a grupos de captura inexistentes na string de substituição são substituídas por uma string vazia.

Exemplos:

{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} - será resolvido como "Problem ID: 123" se um valor como "123 Log line" for recebido
{{ITEM.VALUE}.regsub("fail|error|fault|problem","ERROR")} - será resolvido como "ERROR" se substrings "fail", "error", "fault" ou "problem" forem recebidas (diferencia maiúsculas de minúsculas); retornará uma string vazia se não houver correspondência

Veja mais exemplos.

tr(caracteres,substituição)

Transliteração dos caracteres do valor da macro.

• caracteres - o conjunto de caracteres a serem substituídos;
• substituição - o conjunto de caracteres de substituição correspondentes por posição.

Exemplos:

{{ITEM.VALUE}.tr(abc, xyz)} - substituirá todas as ocorrências de "a" por "x", "b" por "y", "c" por "z"
{{ITEM.VALUE}.tr(abc, xyzq)} - substituirá todas as ocorrências de "a" por "x", "b" por "y", "c" por "z" ("q" é ignorado)
{{ITEM.VALUE}.tr(abcde, xyz)} - substituirá todas as ocorrências de "a" por "x", "b" por "y", "c" por "z", "d" por "z", "e" por "z" (ou seja, xyzzz)
{{ITEM.VALUE}.tr("\\\'", "\/\"")} - substituirá todas as ocorrências de barra invertida por barra, aspas simples por aspas duplas
{{ITEM.VALUE}.tr(A-Z,a-z)} - converterá todas as letras para minúsculas
{{ITEM.VALUE}.tr(0-9a-z,*)} - substituirá todos os números e letras minúsculas por "*"
{{ITEM.VALUE}.tr(0-9,ab)} - substituirá todas as ocorrências de 0 por "a", e substituirá todas as ocorrências de 1, 2, 3, 4, 5, 6, 7, 8 e 9 por "b"
{{ITEM.VALUE}.tr(0-9abcA-L,*)} - substituirá todos os números, caracteres "abc" e o intervalo A-L por "*"
{{ITEM.VALUE}.tr("\n","*")} - substituirá as ocorrências de fim de linha por *
{{ITEM.VALUE}.tr("e", "\n")} - substituirá todos os "e" por fim de linha

Para incluir caracteres literais:

barra invertida - deve ser escapada como \\
aspas simples - deve ser escapada como \'
aspas duplas - deve ser escapada como \"

Sequências de escape suportadas com barra invertida:

\\\\ => \\ - barra invertida dupla para barra invertida simples
\\a  => \a - alerta
\\b  => \b - backspace
\\f  => \f - form feed
\\n  => \n - nova linha
\\r  => \r - retorno
\\t  => \t - tabulação horizontal
\\v  => \v - tabulação vertical

uppercase

Transformação de todos os caracteres do valor da macro em maiúsculas. Funciona com conjuntos de caracteres de byte único (como ASCII) e não suporta UTF-8.

Exemplo:

{{ITEM.VALUE}.uppercase()} - transformará um valor como "Zabbix Server" em "ZABBIX SERVER" (maiúsculas)

urldecode

Decodificando um valor de macro de uma codificação de URL.

Exemplo:

{{ITEM.VALUE}.urldecode()} - irá decodificar um valor como "%2F" em "/"

urlencode

Codificando um valor de macro em codificação de URL.

Exemplo:

{{ITEM.VALUE}.urlencode()} - irá codificar um caractere como "/" em "%2F"

Exemplos adicionais

A tabela abaixo mostra mais exemplos de uso de funções de macro.

:::noteinfo {#IFALIAS} é uma macro LLD e só é definida em contextos de descoberta de baixo nível (regras de descoberta, protótipos e os items/triggers criados a partir deles). Usá-la fora do LLD deixará o token não expandido. :::

Visualizando valores completos de items

Valores longos das macros {ITEM.VALUE} e {ITEM.LASTVALUE} resolvidas para items de texto/log são truncados para 20 caracteres em alguns locais do frontend. Para ver os valores completos dessas macros, você pode usar funções de macro, por exemplo:

{{ITEM.VALUE}.regsub("(.*)", \1)}
{{ITEM.LASTVALUE}.regsub("(.*)", \1)}

Veja também: detalhes das macros {ITEM.VALUE} e {ITEM.LASTVALUE} macro details.