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

宏函数支持用于：

• 内置宏
• 用户宏
• 低级别发现宏
• 表达式宏

宏函数可用于所有支持上述宏的位置。 除非明确说明仅接受宏本身，否则均适用（例如，在配置主机宏或低级别发现规则的过滤器时）。

每个宏仅支持一个函数；不支持链式使用多个宏函数。

支持的函数

以下函数仅列出名称，未附加更多信息。
单击函数可查看完整详情。

函数详细信息

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

btoa

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

示例：

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

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 - 必填格式字符串，与 strftime 函数格式兼容；
• time_shift（可选）- 在格式化之前应用于时间的时间偏移；应以 -<N><time_unit> 或 +<N><time_unit> 开头，其中：
  • N - 要增加或减少的时间单位数量；
  • time_unit - h（小时）、d（天）、w（周）、M（月）或 y（年）。

说明：

• time_shift 参数支持多步时间运算，并且可包含 /<time_unit>，用于将时间偏移到该时间单位的起始位置 （/d - 午夜，/w - 一周的第 1 天（星期一），/M - 一个月的第 1 天，等等）。 示例：-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 编码中解码。

支持以下字符：

示例：

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

htmlencode

将宏值编码为 HTML 编码。

支持以下字符：

示例：

{{ITEM.VALUE}.htmlencode()} - 将把类似 "<" 这样的字符进行 HTML 编码为 "&lt;"

iregsub(pattern,output)

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

参数：

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

说明：

• 如果正则表达式没有匹配项，该函数将返回空字符串。
• 如果函数中的 pattern 是错误的正则表达式，则该宏将被解析为“UNKNOWN”（低级发现宏除外，在这种情况下该函数将被忽略，宏将保持未解析状态）。
• 替换字符串中对不存在的捕获组的引用将被替换为空字符串。

示例：

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

小写

将宏值中的所有字符转换为小写。
适用于单字节字符集（如 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(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)

宏值字符的音译转换。

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

要包含字面字符：

backslash - 必须转义为 \\
single quote - 必须转义为 \'
double quote - 必须转义为 \"

反斜杠支持的转义序列：

\\\\ => \\ - 双反斜杠变为单反斜杠
\\a  => \a - 响铃
\\b  => \b - 退格
\\f  => \f - 换页
\\n  => \n - 换行
\\r  => \r - 回车
\\t  => \t - 水平制表符
\\v  => \v - 垂直制表符

大写

将宏值中的所有字符转换为大写。
适用于单字节字符集（如 ASCII），不支持 UTF-8。

示例：

{{ITEM.VALUE}.uppercase()} - 将把类似 "Zabbix Server" 的值转换为 "ZABBIX SERVER"（大写）

urldecode

将宏值从 URL 编码中解码。

示例：

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

urlencode

将宏值编码为 URL 编码格式。

示例：

{{ITEM.VALUE}.urlencode()} - 将把像 "/" 这样的字符进行 URL 编码为 "%2F"

更多示例

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

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

查看完整的监控项值

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

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

另请参见：{ITEM.VALUE} 和 {ITEM.LASTVALUE} 的 macro details。