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格式。
fmtnum	数字格式化，用于控制小数点后打印的数字位数。
fmttime	时间格式化。
htmldecode	从HTML编码解码宏值。
htmlencode	将宏值编码为HTML编码。
iregsub	通过正则表达式匹配（不区分大小写）提取子字符串。
lowercase	将宏值字符转换为小写。
regrepl	在宏值中替换字符/子字符串。
regsub	通过正则表达式匹配（区分大小写）提取子字符串。
tr	宏值字符的转写。
uppercase	将宏值字符转换为大写。
urldecode	从URL编码解码宏值。
urlencode	将宏值编码为URL编码。

函数详细信息

可选的函数参数由 < > 表示。

btoa

将宏值编码为Base64编码。Base64编码是一种将二进制数据表示为文本的方法，对于通过基于文本的协议存储和安全传输二进制内容非常有用。

示例：

{{ITEM.VALUE}.btoa()} - 将把类似"zabbix"的值Base64编码为"emFiYml4"

此函数自Zabbix 7.0.4版本起得到支持。

    ##### fmtnum(digits) {#fmtnum}

将数字格式化以控制小数点后打印的数字位数。

参数：

digits - 小数点后的数字位数。有效范围：0-20。不会产生尾随零。

示例：

{{ITEM.VALUE}.fmtnum(2)} - 从接收到的值 "24.3483523" 返回 "24.35"
       {{ITEM.VALUE}.fmtnum(0)} - 从接收到的值 "24.3483523" 返回 "24"
       
       
           ##### fmttime(format,<time_shift>) {#fmttime}

时间格式化。
请注意，此函数可以与解析为以下时间格式之一的值的宏一起使用：

hh:mm:ss
yyyy-mm-ddThh:mm:ss[tz]（ISO8601标准）
UNIX时间戳

参数：

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。

示例：

{{TIME}.fmttime(%B)} - 从接收到的值"12:36:01"返回"十月"
       {{TIME}.fmttime(%d %B,-1M/M)} - 从接收到的值"12:36:01"返回"1 九月"
       
       
           ##### htmldecode {#htmldecode}

从HTML编码中解码宏值。此函数自Zabbix 7.0.4版本起得到支持。

以下字符被支持：

Value	Decoded value
`&`	`&`
`<`	`<`
`>`	`>`
`"`	`"`
`'`	`'`
`'`	`'`

示例：

{{ITEM.VALUE}.htmldecode()} - 将像"<"这样的值从HTML编码解码为"<"
       
       
           ##### htmlencode {#htmlencode}

将宏值编码为HTML编码。此功能自Zabbix 7.0.4版本起得到支持。

以下字符被支持：

值	编码后的值
`&`	`&`
`<`	`<`
`>`	`>`
`"`	`"`
`'`	`'`

示例：

{{ITEM.VALUE}.htmlencode()} - 将会把类似"<"的字符HTML编码为"<"
       
       
           ##### iregsub(pattern,output) {#iregsub}

通过正则表达式匹配进行子字符串提取（不区分大小写）。

参数：

pattern - 要匹配的正则表达式；
output - 输出选项。支持 \1 - \9 占位符来捕获组。\0 返回匹配的文本。

注释：

如果正则表达式没有匹配，函数返回空；
如果函数的pattern是一个不正确的正则表达式，那么宏将评估为 'UNKNOWN' （除了低级发现宏，在这种情况下，函数将被忽略，宏将保持未解析）；
替换字符串中对不存在的捕获组的引用将被替换为空字符串。

示例：

{{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} - 如果接收到 "fail"，"error"，"fault"，或 "problem" 子字符串（不区分大小写），将解析为 "ERROR"；如果没有匹配则返回空

lowercase

将所有宏值字符转换为小写。适用于单字节字符集（如ASCII），不支持UTF-8。此函数自Zabbix 7.0.4版本起得到支持。

示例：

{{ITEM.VALUE}.lowercase()} - 将把类似"Zabbix SERVER"的值转换为"zabbix server"（小写）

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

在宏值中替换字符/子字符串。注意，此函数仅在使用libpcre2库时受支持。如果Zabbix server/proxy使用libpcre编译，此函数将返回UNKNOWN。此函数自Zabbix 7.0.4起受支持。

参数：

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\)", "")} - 将在item值中替换多个部分

regsub(pattern,output)

通过正则表达式匹配进行子字符串提取（区分大小写）。

参数：

pattern - 要匹配的正则表达式；
output - 输出选项。支持 \1 - \9 占位符来捕获组。\0 返回匹配的文本。

注释：

如果正则表达式没有匹配，函数返回空；
如果函数的pattern是一个不正确的正则表达式，那么宏将评估为 'UNKNOWN' （除了低级发现宏，在这种情况下，函数将被忽略，宏将保持未解析）；
替换字符串中对不存在的捕获组的引用将被替换为空字符串。

示例：

{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} - 如果接收到类似 "123 Log line" 的值，将解析为 "Problem ID: 123"
       {{ITEM.VALUE}.regsub("fail|error|fault|problem","ERROR")} - 如果接收到 "fail"、"error"、"fault" 或 "problem" 子字符串（区分大小写），将解析为 "ERROR"；如果没有匹配，则为空

参见更多示例。

    ##### tr(characters,replacement) {#tr}

宏值字符的转写。此功能自Zabbix 7.0.4版本起得到支持。

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"替换为行尾

要包含字面字符：

反斜杠 - 必须转义为\\
       单引号 - 必须转义为\'
       双引号 - 必须转义为\"

支持的反斜杠转义序列：

\\\\ => \\ - 双反斜杠转换为单反斜杠
       \\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 {#urldecode}

将宏值从URL编码解码。此功能自Zabbix 7.0.4版本起得到支持。

示例：

{{ITEM.VALUE}.urldecode()} - 将像"%2F"这样的值从URL编码解码为"/"

urlencode

将宏值编码为URL编码。此功能自Zabbix 7.0.4版本起得到支持。

示例：

{{ITEM.VALUE}.urlencode()} - 将把类似"/"的字符编码为"%2F"

额外示例

下表展示了使用宏函数的更多示例。

宏函数	接收的值	输出
`{{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` (无效的正则表达式)
`{{#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)}` (无效的正则表达式)
`{$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:"{{#M}.regsub(\"(.*)_([0-9]+\", \1)}"}` (无效的正则表达式)
`"{$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)}\"}"` (无效的正则表达式)

查看完整监控项值

文本/日志监控项的已解析{ITEM.VALUE}和{ITEM.LASTVALUE}宏的长值在前端某些位置被截断为20个字符。要查看这些宏的完整值，您可以使用宏函数，例如：

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

另请参阅：{ITEM.VALUE}和{ITEM.LASTVALUE} 宏详情。

Documentation