[comment]: # attributes: notoc [comment]: # ({09129833-0458cee0}) # 1 Функции макросов #### Обзор Функции макросов позволяют настраивать значения [макросов](/manual/config/macros) (например, укорачивать их или извлекать определенные подстроки), что упрощает работу с ними. Синтаксис функции макроса: ```default {macro.func(params)} ``` где - **macro** - макрос, который нужно настроить; - **func** - функция, которую нужно применить (см. [поддерживаемые функции](#supported-functions)); - **params** - список параметров функции, разделенных запятыми; они должны быть **заключены в двойные кавычки**, если: - начинаются с пробела или двойной кавычки; - содержат закрывающую скобку или запятую. Например: ```default {{TIME}.fmttime(format,time_shift)} {{ITEM.VALUE}.regsub(pattern, output)} {{$USERMACRO}.regsub(pattern, output)} {{#LLDMACRO}.regsub(pattern, output)} ``` Функции макросов поддерживаются для - [встроенных макросов](/manual/appendix/macros/supported_by_location) - [пользовательских макросов](/manual/appendix/macros/supported_by_location#other-macro-types) - [макросов низкоуровневого обнаружения](/manual/appendix/macros/supported_by_location#other-macro-types) - [макросов выражений](/manual/appendix/macros/supported_by_location#other-macro-types) Функции макросов можно использовать во всех местах, где поддерживаются перечисленные макросы. Это применимо, если явно не указано, что ожидается только макрос (например, при настройке [макросов узла сети](/manual/config/hosts/host#configuration) или [фильтров](/manual/discovery/low_level_discovery#filter) правила низкоуровневого обнаружения). Для каждого макроса поддерживается только одна функция; цепочки из нескольких функций макросов не поддерживаются. :::noteclassic См. [примеры экранирования](/manual/appendix/escaping) для случаев, когда функции макросов используются внутри других контекстов (функция, ключ элемента данных, другой макрос и т. д.). ::: [comment]: # ({/09129833-0458cee0}) [comment]: # ({f9dac088-b8563887}) #### Поддерживаемые функции Функции перечислены без дополнительной информации. Нажмите на функцию, чтобы увидеть полные сведения. |Function|Description| |--|--------| |[btoa](#btoa)|Кодирование значения макроса в Base64.| |[fmtnum](#fmtnum)|Форматирование числа для управления количеством цифр, выводимых после десятичной точки.| |[fmttime](#fmttime)|Форматирование времени.| |[htmldecode](#htmldecode)|Декодирование значения макроса из HTML-кодирования.| |[htmlencode](#htmlencode)|Кодирование значения макроса в HTML-кодирование.| |[iregsub](#iregsub)|Извлечение подстроки по совпадению с регулярным выражением (без учета регистра).| |[lowercase](#lowercase)|Преобразование символов значения макроса в нижний регистр.| |[regrepl](#regrepl)|Замена символа/подстроки в значении макроса.| |[regsub](#regsub)|Извлечение подстроки по совпадению с регулярным выражением (с учетом регистра).| |[tr](#tr)|Транслитерация символов значения макроса.| |[uppercase](#uppercase)|Преобразование символов значения макроса в верхний регистр.| |[urldecode](#urldecode)|Декодирование значения макроса из URL-кодирования.| |[urlencode](#urlencode)|Кодирование значения макроса в URL-кодирование.| [comment]: # ({/f9dac088-b8563887}) [comment]: # ({91058888-c1632a9e}) #### Подробности функций Необязательные параметры функций обозначены угловыми скобками (< >). [comment]: # ({/91058888-c1632a9e}) [comment]: # ({d8d5fafe-6e2e93df}) ##### btoa {#btoa} Кодирование значения макроса в Base64. Кодирование Base64 — это способ представления двоичных данных в виде текста, который полезен для хранения и безопасной передачи двоимого содержимого по текстовым протоколам. Пример: ```default {{ITEM.VALUE}.btoa()} - закодирует значение, например "zabbix", в Base64, в результате чего получится "emFiYml4" ``` [comment]: # ({/d8d5fafe-6e2e93df}) [comment]: # ({31245134-4df3fd19}) ##### fmtnum(цифры) {#fmtnum} Форматирование числа для управления количеством цифр, выводимых после десятичной точки. Параметры: - **цифры** — количество цифр после десятичной точки. Допустимый диапазон: 0-20. Конечные нули будут обрезаны. Примеры: ```default {{ITEM.VALUE}.fmtnum(2)} — вернёт «24.35» из полученного значения «24.3483523» {{ITEM.VALUE}.fmtnum(0)} — вернёт «24» из полученного значения «24.3483523» ``` [comment]: # ({/31245134-4df3fd19}) [comment]: # ({a8d94ee5-3caa4dc7}) ##### fmttime(format,) {#fmttime} Форматирование времени.
Обратите внимание, что эту функцию можно использовать с макросами, которые преобразуются в значение в одном из следующих форматов времени: - `hh:mm:ss` - `yyyy-mm-ddThh:mm:ss[tz]` (стандарт ISO8601) - UNIX timestamp Параметры: - **format** - обязательная строка формата, совместимая с форматированием функции `strftime`; - **time\_shift** (необязательно) - сдвиг времени, применяемый к времени перед форматированием; должен начинаться с `-` или `+`, где: - `N` - количество единиц времени, которые нужно прибавить или вычесть; - `time_unit` - h (час), d (день), w (неделя), M (месяц) или y (год). Комментарии: - Параметр `time_shift` поддерживает многошаговые операции со временем и может включать `/` для сдвига к началу единицы времени (`/d` - полночь, `/w` - первый день недели (понедельник), `/M` - первый день месяца и т. д.). Примеры: `-1w` - ровно 7 дней назад; `-1w/w` - понедельник предыдущей недели; `-1w/w+1d` - вторник предыдущей недели. - Операции со временем вычисляются слева направо без приоритетов. Например, `-1M/d+1h/w` будет разобрано как `((-1M/d)+1h)/w`. Примеры: ```default {{TIMESTAMP}.fmttime(%B)} - вернет "October" из полученного значения "1633098961" {{TIMESTAMP}.fmttime(%d %B,-1M/M)} - вернет "1 September" из полученного значения "1633098961" ``` [comment]: # ({/a8d94ee5-3caa4dc7}) [comment]: # ({d224cb43-e5cb24ab}) ##### htmldecode {#htmldecode} Декодирование значения макроса из HTML-кодировки. Поддерживаются следующие символы: |Value|Decoded value| |----|------| |`&`|`&`| |`<`|`<`| |`>`|`>`| |`"`|`"`| |`'`|`'`| |`'`|`'`| Пример: ```default {{ITEM.VALUE}.htmldecode()} - выполнит HTML-декодирование значения, например "<" в "<" ``` [comment]: # ({/d224cb43-e5cb24ab}) [comment]: # ({f78164e5-b0e6d63f}) ##### htmlencode {#htmlencode} Кодирование значения макроса в HTML-кодировку. Поддерживаются следующие символы: |Value|Encoded value| |----|------| |`&`|`&`| |`<`|`<`| |`>`|`>`| |`"`|`"`| |`'`|`'`| Пример: ```default {{ITEM.VALUE}.htmlencode()} - выполнит HTML-кодирование символа, например "<", в "<" ``` [comment]: # ({/f78164e5-b0e6d63f}) [comment]: # ({edaa6df7-e78b5abd}) ##### iregsub(шаблон,вывод) {#iregsub} Извлечение подстроки помощью сопоставления с регулярным выражением (без учёта регистра). Parameters: - **шаблон** — регулярное выражение для поиска совпадения; - **вывод** — опции вывода. Для захвата групп поддерживаются местозаменители **\\1 - \\9**. Заменитель **\\0** вернёт совпавший текст. Комментарии: - Если нет совпадений с регулярным выражением, функция возвращает пустую строку. - Если шаблон функции не является корректным регулярным выражением, то макрос раскрывается в «НЕИЗВЕСТНО» (за исключением макросов низкоуровневого обнаружения, где в этом случае функция будет проигнорирована и макрос останется нераскрытым). - Ссылки на несуществующие скобочные группы в строке замены заменяются пустой строкой. Пример: ```default {{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} — будет раскрыто в «ERROR», если получены подстроки «fail», «error», «fault» или «problem» (без учёта регистра); вернёт пустую строку, если совпадений нет ``` [comment]: # ({/edaa6df7-e78b5abd}) [comment]: # ({9186768b-b7de9b23}) ##### lowercase {#lowercase} Преобразование всех символов значения макроса в нижний регистр. Работает с однобайтовыми наборами символов (например, ASCII) и не поддерживает UTF-8. Пример: ```default {{ITEM.VALUE}.lowercase()} - преобразует значение, например "Zabbix SERVER", в "zabbix server" (lowercase) ``` [comment]: # ({/9186768b-b7de9b23}) [comment]: # ({2064b2f8-2d4d3410}) ##### regrepl(pattern,replacement,,,...) {#regrepl} Замена символа/подстроки в значении макроса. Параметры: - **pattern** - регулярное выражение для сопоставления; - **replacement** - строка замены. В строках замены поддерживаются заполнители **\\1 - \\9** для захвата групп. Комментарии: - шаблоны и замены обрабатываются последовательно, при этом каждая последующая пара применяется в соответствии с результатом предыдущей замены; - ссылки на несуществующие группы захвата в строке замены заменяются пустой строкой. Примеры: ```default {{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\)", "")} - заменит несколько частей в значении элемента данных ``` [comment]: # ({/2064b2f8-2d4d3410}) [comment]: # ({825c2e80-a8dcf3b5}) ##### regsub(шаблон,вывод) {#regsub} Извлечение подстроки помощью сопоставления с регулярным выражением (с учётом регистра). Параметры: - **шаблон** — регулярное выражение для поиска совпадения; - **вывод** — опции вывода. Для захвата групп поддерживаются местозаменители **\\1 - \\9**. Заменитель **\\0** вернёт совпавший текст. Комментарии: - Если нет совпадений с регулярным выражением, функция ничего не возвращает. - Если шаблон функции не является корректным регулярным выражением, то макрос раскрывается в «НЕИЗВЕСТНО» (за исключением макросов низкоуровневого обнаружения, где в этом случае функция будет проигнорирована и макрос останется нераскрытым). - Ссылки на несуществующие скобочные группы в строке замены заменяются пустой строкой. Примеры: ```default {{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» (с учётом регистра); вернёт пустую строку, если совпадений нет ``` Смотрите [ещё примеры](#дополнительные-примеры). [comment]: # ({/825c2e80-a8dcf3b5}) [comment]: # ({40e84cc5-d7660986}) ##### tr(characters,replacement) {#tr} Транслитерация значения макроса characters. - **characters** - набор символов для замены; - **replacement** - набор символов замены, соответствующих по позиции. Примеры: ```default {{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" на конец строки ``` Чтобы включить буквальные символы: ```default обратная косая черта - должна быть экранирована как \\ одинарная кавычка - должна быть экранирована как \' двойная кавычка - должна быть экранирована как \" ``` Поддерживаемые escape-последовательности с обратной косой чертой: ```default \\\\ => \\ - двойная обратная косая черта в одинарную обратную косую черту \\a => \a - сигнал \\b => \b - backspace \\f => \f - перевод страницы \\n => \n - перевод строки \\r => \r - возврат каретки \\t => \t - горизонтальная табуляция \\v => \v - вертикальная табуляция ``` [comment]: # ({/40e84cc5-d7660986}) [comment]: # ({57ab4e3a-8315e479}) ##### верхний регистр {#uppercase} Преобразование всех символов значения макроса в верхний регистр. Работает с однобайтовыми наборами символов (например, ASCII) и не поддерживает UTF-8. Пример: ```default {{ITEM.VALUE}.uppercase()} - преобразует значение, например "Zabbix Server", в "ZABBIX SERVER" (верхний регистр) ``` [comment]: # ({/57ab4e3a-8315e479}) [comment]: # ({9f54b4cb-15465392}) ##### urldecode {#urldecode} Декодирование значения макроса из URL-кодировки. Пример: ```default {{ITEM.VALUE}.urldecode()} - выполнит URL-декодирование значения вроде "%2F" в "/" ``` [comment]: # ({/9f54b4cb-15465392}) [comment]: # ({725aedc6-362f6ccf}) ##### urlencode {#urlencode} Кодирование значения макроса в URL-кодировку. Пример: ```default {{ITEM.VALUE}.urlencode()} - закодирует символ, например "/", в "%2F" ``` [comment]: # ({/725aedc6-362f6ccf}) [comment]: # ({a95b22c2-148bfc16}) #### Дополнительные примеры В таблице ниже приведено больше примеров использования функций макросов. :::noteinfo `{#IFALIAS}` — это [LLD-макрос](/manual/config/macros/lld_macros) и определяется только в контекстах низкоуровневого обнаружения (правила обнаружения, прототипы и созданные на их основе элементы данных/триггеры). При использовании вне LLD токен не будет раскрыт. ::: |Macro function|Received value|Output| |-------------|----|-------------| |`{{ITEM.VALUE}.regsub(^[0-9]+, Problem)}`|`123Log line`|`Problem`| |`{{ITEM.VALUE}.regsub("^([0-9]+)", "Problem")}`|`123 Log line`|`Problem`| |`{{ITEM.VALUE}.regsub(".*", "Problem ID: \1")}`|`Log line`|`Problem ID: `| |`{{ITEM.VALUE}.regsub("^(\w+).*?([0-9]+)", " Problem ID: \1_\2 ")}`|`MySQL crashed errno 123`|` Problem ID: MySQL_123 `| |`{{ITEM.VALUE}.regsub("([1-9]+", "Problem ID: \1")}`|`123 Log line`|`*UNKNOWN*` (invalid regular expression)| |`{{#IFALIAS}.regsub("(.*)_([0-9]+)", \1)}`|`customername_1`|`customername`| |`{{#IFALIAS}.regsub("(.*)_([0-9]+)", \2)}`|`customername_1`|`1`| |`{{#IFALIAS}.regsub("(.*)_([0-9]+", \1)}`|`customername_1`|`{{#IFALIAS}.regsub("(.*)_([0-9]+", \1)}` (invalid regular expression)| |`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \1)}"}`|`customername_1`|`{$MACRO:"customername"}`| |`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \2)}"}`|`customername_1`|`{$MACRO:"1"}`| |`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+\", \1)}"}`|`customername_1`|`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+\", \1)}"}` (invalid regular expression)| |`"{$MACRO:"\{{#IFALIAS}.regsub("(.*)_([0-9]+)", \1)}\"}"`|`customername_1`|`"{$MACRO:"\customername\"}"`| |`"{$MACRO:"\{{#IFALIAS}.regsub("(.*)_([0-9]+)", \2)}\"}"`|`customername_1`|`"{$MACRO:"\1\"}"`| |`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}"`|`customername_1`|`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}"` (invalid regular expression)| ##### Просмотр полных значений элементов данных Длинные значения раскрытых макросов {ITEM.VALUE} и {ITEM.LASTVALUE} для текстовых/логовых элементов данных в некоторых местах веб-интерфейса обрезаются до 20 символов. Чтобы увидеть полные значения этих макросов, можно использовать функции макросов, например: ```default {{ITEM.VALUE}.regsub("(.*)", \1)} {{ITEM.LASTVALUE}.regsub("(.*)", \1)} ``` См. также: {ITEM.VALUE} и {ITEM.LASTVALUE} [подробности о макросах](/manual/appendix/macros/supported_by_location). [comment]: # ({/a95b22c2-148bfc16})