1 Функции макросов

Обзор

Функции макросов позволяют настраивать значения макросов (например, укорачивать их или извлекать определенные подстроки), что упрощает работу с ними.

Синтаксис функции макроса:

{macro.func(params)}

где

• macro - макрос, который нужно настроить;
• func - функция, которую нужно применить (см. поддерживаемые функции);
• params - список параметров функции, разделенных запятыми; они должны быть заключены в двойные кавычки, если:
  • начинаются с пробела или двойной кавычки;
  • содержат закрывающую скобку или запятую.

Например:

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

Функции макросов поддерживаются для

• встроенных макросов
• пользовательских макросов
• макросов низкоуровневого обнаружения
• макросов выражений

Функции макросов можно использовать во всех местах, где поддерживаются перечисленные макросы. Это применимо, если явно не указано, что ожидается только макрос (например, при настройке макросов узла сети или фильтров правила низкоуровневого обнаружения).

Для каждого макроса поддерживается только одна функция; цепочки из нескольких функций макросов не поддерживаются.

Поддерживаемые функции

Функции перечислены без дополнительной информации. Нажмите на функцию, чтобы увидеть полные сведения.

Подробности функций

Необязательные параметры функций обозначены угловыми скобками (< >).

btoa

Кодирование значения макроса в Base64. Кодирование Base64 — это способ представления двоичных данных в виде текста, который полезен для хранения и безопасной передачи двоимого содержимого по текстовым протоколам.

Пример:

{{ITEM.VALUE}.btoa()} - закодирует значение, например "zabbix", в Base64, в результате чего получится "emFiYml4"

fmtnum(цифры)

Форматирование числа для управления количеством цифр, выводимых после десятичной точки.

Параметры:

• цифры — количество цифр после десятичной точки. Допустимый диапазон: 0-20. Конечные нули будут обрезаны.

Примеры:

{{ITEM.VALUE}.fmtnum(2)} — вернёт «24.35» из полученного значения «24.3483523»
{{ITEM.VALUE}.fmtnum(0)} — вернёт «24» из полученного значения «24.3483523»

fmttime(format,<time_shift>)

Форматирование времени.
Обратите внимание, что эту функцию можно использовать с макросами, которые преобразуются в значение в одном из следующих форматов времени:

• hh:mm:ss
• yyyy-mm-ddThh:mm:ss[tz] (стандарт ISO8601)
• UNIX timestamp

Параметры:

• format - обязательная строка формата, совместимая с форматированием функции strftime;
• time_shift (необязательно) - сдвиг времени, применяемый к времени перед форматированием; должен начинаться с -<N><time_unit> или +<N><time_unit>, где:
  • N - количество единиц времени, которые нужно прибавить или вычесть;
  • time_unit - h (час), d (день), w (неделя), M (месяц) или y (год).

Комментарии:

• Параметр time_shift поддерживает многошаговые операции со временем и может включать /<time_unit> для сдвига к началу единицы времени (/d - полночь, /w - первый день недели (понедельник), /M - первый день месяца и т. д.). Примеры: -1w - ровно 7 дней назад; -1w/w - понедельник предыдущей недели; -1w/w+1d - вторник предыдущей недели.
• Операции со временем вычисляются слева направо без приоритетов. Например, -1M/d+1h/w будет разобрано как ((-1M/d)+1h)/w.

Примеры:

{{TIMESTAMP}.fmttime(%B)} - вернет "October" из полученного значения "1633098961"
{{TIMESTAMP}.fmttime(%d %B,-1M/M)} - вернет "1 September" из полученного значения "1633098961"

htmldecode

Декодирование значения макроса из HTML-кодировки.

Поддерживаются следующие символы:

Пример:

{{ITEM.VALUE}.htmldecode()} - выполнит HTML-декодирование значения, например "&lt;" в "<"

htmlencode

Кодирование значения макроса в HTML-кодировку.

Поддерживаются следующие символы:

Пример:

{{ITEM.VALUE}.htmlencode()} - выполнит HTML-кодирование символа, например "<", в "&lt;"

iregsub(шаблон,вывод)

Извлечение подстроки помощью сопоставления с регулярным выражением (без учёта регистра).

Parameters:

• шаблон — регулярное выражение для поиска совпадения;
• вывод — опции вывода. Для захвата групп поддерживаются местозаменители \1 - \9. Заменитель \0 вернёт совпавший текст.

Комментарии:

• Если нет совпадений с регулярным выражением, функция возвращает пустую строку.
• Если шаблон функции не является корректным регулярным выражением, то макрос раскрывается в «НЕИЗВЕСТНО» (за исключением макросов низкоуровневого обнаружения, где в этом случае функция будет проигнорирована и макрос останется нераскрытым).
• Ссылки на несуществующие скобочные группы в строке замены заменяются пустой строкой.

Пример:

{{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} — будет раскрыто в «ERROR», если получены подстроки «fail», «error», «fault» или «problem» (без учёта регистра); вернёт пустую строку, если совпадений нет

lowercase

Преобразование всех символов значения макроса в нижний регистр.
Работает с однобайтовыми наборами символов (например, ASCII) и не поддерживает UTF-8.

Пример:

{{ITEM.VALUE}.lowercase()} - преобразует значение, например "Zabbix SERVER", в "zabbix server" (lowercase)

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

Замена символа/подстроки в значении макроса.

Параметры:

• pattern - регулярное выражение для сопоставления;
• replacement - строка замены. В строках замены поддерживаются заполнители \1 - \9 для захвата групп.

Комментарии:

• шаблоны и замены обрабатываются последовательно, при этом каждая последующая пара применяется в соответствии с результатом предыдущей замены;
• ссылки на несуществующие группы захвата в строке замены заменяются пустой строкой.

Примеры:

{{ITEM.VALUE}.regrepl("oldParam", "newParam")} - заменит "oldParam" на "newParam"
{{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - все не буквенные символы будут экранированы обратной косой чертой
{$THRESHOLD:"{{#FSNAME}.regrepl(\"\\$\",\"\")}"} - удалит завершающую обратную косую черту (например, чтобы заменить "C:\" на "C:")
{{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - заменит несколько частей в значении элемента данных

regsub(шаблон,вывод)

Извлечение подстроки помощью сопоставления с регулярным выражением (с учётом регистра).

Параметры:

• шаблон — регулярное выражение для поиска совпадения;
• вывод — опции вывода. Для захвата групп поддерживаются местозаменители \1 - \9. Заменитель \0 вернёт совпавший текст.

Комментарии:

• Если нет совпадений с регулярным выражением, функция ничего не возвращает.
• Если шаблон функции не является корректным регулярным выражением, то макрос раскрывается в «НЕИЗВЕСТНО» (за исключением макросов низкоуровневого обнаружения, где в этом случае функция будет проигнорирована и макрос останется нераскрытым).
• Ссылки на несуществующие скобочные группы в строке замены заменяются пустой строкой.

Примеры:

{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} — будет раскрыто в «Problem ID: 123», если получено значение наподобие «123 Log line»
{{ITEM.VALUE}.regsub("fail|error|fault|problem","ERROR")} — будет раскрыто в «ERROR», если получены подстроки «fail», «error», «fault» или «problem» (с учётом регистра); вернёт пустую строку, если совпадений нет

Смотрите ещё примеры.

tr(characters,replacement)

Транслитерация значения макроса characters.

• characters - набор символов для замены;
• replacement - набор символов замены, соответствующих по позиции.

Примеры:

{{ITEM.VALUE}.tr(abc, xyz)} - заменит все вхождения "a" на "x", "b" на "y", "c" на "z"
{{ITEM.VALUE}.tr(abc, xyzq)} - заменит все вхождения "a" на "x", "b" на "y", "c" на "z" ("q" игнорируется)
{{ITEM.VALUE}.tr(abcde, xyz)} - заменит все вхождения "a" на "x", "b" на "y", "c" на "z", "d" на "z", "e" на "z" (то есть xyzzz)
{{ITEM.VALUE}.tr("\\\'", "\/\"")} - заменит все вхождения обратной косой черты на прямую косую черту, одинарные кавычки на двойные кавычки
{{ITEM.VALUE}.tr(A-Z,a-z)} - преобразует все буквы в нижний регистр
{{ITEM.VALUE}.tr(0-9a-z,*)} - заменит все цифры и строчные буквы на "*"
{{ITEM.VALUE}.tr(0-9,ab)} - заменит все вхождения 0 на "a", а все вхождения 1, 2, 3, 4, 5, 6, 7, 8 и 9 на "b"
{{ITEM.VALUE}.tr(0-9abcA-L,*)} - заменит все цифры, символы "abc" и диапазон A-L на "*"
{{ITEM.VALUE}.tr("\n","*")} - заменит вхождения конца строки на *
{{ITEM.VALUE}.tr("e", "\n")} - заменит все "e" на конец строки

Чтобы включить буквальные символы:

обратная косая черта - должна быть экранирована как \\
одинарная кавычка - должна быть экранирована как \'
двойная кавычка - должна быть экранирована как \"

Поддерживаемые escape-последовательности с обратной косой чертой:

\\\\ => \\ - двойная обратная косая черта в одинарную обратную косую черту
\\a  => \a - сигнал
\\b  => \b - backspace
\\f  => \f - перевод страницы
\\n  => \n - перевод строки
\\r  => \r - возврат каретки
\\t  => \t - горизонтальная табуляция
\\v  => \v - вертикальная табуляция

верхний регистр

Преобразование всех символов значения макроса в верхний регистр.
Работает с однобайтовыми наборами символов (например, ASCII) и не поддерживает UTF-8.

Пример:

{{ITEM.VALUE}.uppercase()} - преобразует значение, например "Zabbix Server", в "ZABBIX SERVER" (верхний регистр)

urldecode

Декодирование значения макроса из URL-кодировки.

Пример:

{{ITEM.VALUE}.urldecode()} - выполнит URL-декодирование значения вроде "%2F" в "/"

urlencode

Кодирование значения макроса в URL-кодировку.

Пример:

{{ITEM.VALUE}.urlencode()} - закодирует символ, например "/", в "%2F"

Дополнительные примеры

В таблице ниже приведено больше примеров использования функций макросов.

:::noteinfo {#IFALIAS} — это LLD-макрос и определяется только в контекстах низкоуровневого обнаружения (правила обнаружения, прототипы и созданные на их основе элементы данных/триггеры). При использовании вне LLD токен не будет раскрыт. :::

Просмотр полных значений элементов данных

Длинные значения раскрытых макросов {ITEM.VALUE} и {ITEM.LASTVALUE} для текстовых/логовых элементов данных в некоторых местах веб-интерфейса обрезаются до 20 символов. Чтобы увидеть полные значения этих макросов, можно использовать функции макросов, например:

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

См. также: {ITEM.VALUE} и {ITEM.LASTVALUE} подробности о макросах.