1 宏函数

概述

宏函数提供了自定义macro值的功能（例如，缩短或提取特定子字符串），使其更易于使用。

宏函数的语法为：

{macro.func(params)}

其中：

• macro - 要自定义的宏；
• func - 要应用的函数（参见支持的函数）；
• params - 逗号分隔的函数参数列表，如果参数：
  • 以空格或双引号开头；
  • 包含右括号或逗号； 则必须使用双引号括起。

例如：

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

支持在以下位置使用宏函数：

• Built-in macros
• 其他宏类型
• 其他宏类型
• 其他宏类型

宏函数可以在所有支持列出宏的位置使用。除非明确说明仅接受宏（例如，配置配置或低级别自动发现规则的过滤器时）。

另请参阅：宏函数

每个宏仅支持一个函数；不支持多个宏函数串联使用。

支持的函数

函数列表未包含额外信息。点击函数名称可查看完整详情。

函数详情

可选函数参数由 < > 标识。

btoa

将宏值编码为Base64格式。Base64编码是一种将二进制数据表示为文本的方法，适用于在基于文本的协议中存储和安全传输二进制内容。

示例：

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

此功能自Zabbix 7.0.4 起支持。

fmtnum(digits)

数字格式化以控制小数点后显示的位数。

参数：

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

示例：

{{ITEM.VALUE}.fmtnum(2)} - 从接收到的值 "24.3483523" 将返回 "24.35"
{{ITEM.VALUE}.fmtnum(0)} - 从接收到的值 "24.3483523" 将返回 "24"

fmttime(format,<time_shift>)

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

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

参数：

• format - 必填格式 string，与 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)} - 将从接收到的值 "1633098961" 返回 "October"
{{TIME}.fmttime(%d %B,-1M/M)} - 将从接收到的值 "1633098961" 返回 "1 September"

htmldecode

从HTML编码中解码宏值。此函数自Zabbix 7.0.4起受支持。

支持以下字符：

示例：

{{ITEM.VALUE}.htmldecode()} - 将类似"&lt;"的值解码为"<"

htmlencode

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

支持以下字符：

示例：

{{ITEM.VALUE}.htmlencode()} - 将会把字符如 "<" 编码为 "&lt;"

iregsub(pattern,output)

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

参数：

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

注释：

• 如果正则表达式没有匹配项，该函数不返回任何内容；
• 如果函数的模式是一个不正确的正则表达式，则宏将解析为 '未知' （低级别发现宏除外，在这种情况下，该函数将被忽略，宏将保持未解析状态）；
• 替换 string 中对不存在的捕获组的引用将被替换为空的 string。

示例：

{{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 - 替换的 string。替换字符串中支持使用 \1 - \9 占位符来捕获组。

备注：

• 模式和替换是按顺序处理的，后续的每一对模式/替换是根据前一次替换的结果进行应用的；
• 替换 string 中对不存在的捕获组的引用将被替换为空的 string。

示例：

{{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(pattern,output)

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

参数：

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

注释：

• 如果正则表达式没有匹配项，函数将不返回任何内容；
• 如果函数的模式是一个不正确的正则表达式，则宏将解析为 '未知' （低级别发现宏除外，在这种情况下函数将被忽略，并且宏将保持未解析状态）；
• 替换 string 中对不存在的捕获组的引用将被替换为空 string。

示例：

{{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)

宏值字符的转写。此功能自 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

对URL编码的宏值进行解码。此功能自Zabbix 7.0.4起受支持。

示例：

{{ITEM.VALUE}.urldecode()} - 将对类似"%2F"的值进行URL解码为"/"

urlencode

将宏值编码为URL编码格式。此功能自Zabbix 7.0.4起受支持。

示例：

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

附加示例

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

:::noteinfo {#IFALIAS} 是一个LLD macros 且仅在低级发现上下文（发现规则、原型及由此创建的监控项/触发器）中定义. 在LLD之外使用该标记将导致其无法展开.

:::

查看完整监控项值

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

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

另请参阅: {ITEM.VALUE} 和 {ITEM.LASTVALUE} macro details.