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

Обзор

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

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

{макрос.функция(параметры)}

где:

• макрос — настраиваемый макрос;
• функция — применяемая функция (смотрите поддерживаемые функции);
• параметры — список параметров функции, разделённых запятыми; параметры должны быть заключены в двойные кавычки, если они:
  • начинаются с пробела или двойных кавычек;
  • содержат закрывающую круглую скобку («)») или запятую («,»).

Например:

{{TIME}.fmttime(формат,сдвиг_времени)}
       {{ITEM.VALUE}.regsub(шаблон, вывод)}
       {{$USERMACRO}.regsub(шаблон, вывод)}
       {{#LLDMACRO}.regsub(шаблон, вывод)}

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

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

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

Смотрите также: известные проблемы

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

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

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

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

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

btoa

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

Пример:

{{ITEM.VALUE}.btoa()} — закодирует значение в формат Base64; например, «zabbix» будет преобразовано в «emFiYml4»

Эта функция поддерживается, начиная с Zabbix версии 7.0.4.

fmtnum(цифры)

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

Параметры:

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

Примеры:

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

fmttime(формат,<сдвиг_времени>)

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

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

Параметры:

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

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

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

Примеры:

{{TIME}.fmttime(%B)} — вернёт «October» из полученного значения «12:36:01»
       {{TIME}.fmttime(%d %B,-1M/M)} — вернёт «1 September» из полученного значения «12:36:01»

htmldecode

Декодирование значения макроса из кодировки HTML. Эта функция поддерживается, начиная с Zabbix версии 7.0.4.

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

Пример:

{{ITEM.VALUE}.htmldecode()} — декодирует значение из кодировки HTML, например, преобразует «<» в «<»  

htmlencode

Кодирование значения макроса в кодировку HTML. Эта функция поддерживается, начиная с Zabbix версии 7.0.4.

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

Пример:

{{ITEM.VALUE}.htmlencode()} — закодирует значение в кодировку HTML, например, преобразует «<» в «<»  

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

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

Parameters:

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

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

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

Пример:

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

lowercase

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

Пример:

{{ITEM.VALUE}.lowercase()} — преобразует значение типа «Zabbix SERVER» в «zabbix server» (нижний регистр)

regrepl(шаблон,замена,<шаблон2>,<замена2>,...)

Замена символа/подстроки в значении макроса. Обратите внимание, что эта функция поддерживается только с библиотекой libpcre2. Если Zabbix сервер/прокси был скомпилирован с libpcre, эта функция вернет UNKNOWN. Эта функция поддерживается, начиная с Zabbix версии 7.0.4.

Параметры:

• шаблон — регулярное выражение для поиска совпадения;
• замена — строка замены. Для захвата групп в строке замены поддерживаются местозаменители \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(символы, замена)

Транслитерация символов значения макроса. Эта функция поддерживается, начиная с Zabbix версии 7.0.4.

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

Примеры:

{{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» на перевод строки

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

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

Поддерживаемые управляющие последовательности с обратной косой чертой:

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

uppercase

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

Пример:

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

urldecode

Декодирование значения макроса из URL-кодировки. Эта функция поддерживается, начиная с версии Zabbix 7.0.4.

Пример:

{{ITEM.VALUE}.urldecode()} — будет декодировать URL-значение наподобие «%2F» в «/»

urlencode

Кодирование значения макроса в URL-кодировку. Эта функция поддерживается, начиная с версии Zabbix 7.0.4.

Пример:

{{ITEM.VALUE}.urlencode()} — будет URL-кодировать, наподобие символа «/» в «%2F»

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

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

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

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

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

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