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()} - закодирует в Base64 значение, например "zabbix", в "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" (нижний регистр)

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 — набор символов для замены;
• 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 - alert
\\b  => \b - backspace
\\f  => \f - перевод страницы
\\n  => \n - новая строка
\\r  => \r - возврат каретки
\\t  => \t - горизонтальная табуляция
\\v  => \v - вертикальная табуляция

uppercase

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

Пример:

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

urldecode

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

Пример:

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

urlencode

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

Пример:

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

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

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

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

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

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

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

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