[comment]: # ({d30dc182-d30dc182})
# 2 用户宏
[comment]: # ({/d30dc182-d30dc182})
[comment]: # ({c282a934-3e220640})
#### 概述
除了开箱即用的宏[supported](/manual/appendix/macros/supported_by_location)外，Zabbix还支持用户宏以实现更高的灵活性。
用户宏可以在全局、模板和主机级别定义。这些宏具有特殊语法：
{$MACRO}
Zabbix按照以下优先级解析宏：
1. 主机级别宏（首先检查）
2. 为主机的一级模板（即直接链接到主机的模板）定义的宏，按模板ID排序
3. 为主机的二级模板定义的宏，按模板ID排序
4. 为主机的三级模板定义的宏，按模板ID排序，以此类推
5. 全局宏（最后检查）
换句话说，如果一个主机不存在某个宏，Zabbix将尝试在主机的逐级深层模板中查找。如果仍未找到，将使用全局宏（如果存在）。
::: notewarning
如果**同名宏**存在于同一级别的多个链接模板中，将使用ID最小的模板中的宏。因此在多个模板中使用同名宏存在配置风险。
:::
如果Zabbix无法找到宏，则该宏不会被解析。
::: noteimportant
在配置部分（例如触发器列表）中，宏（包括用户宏）按设计保持未解析状态，以使复杂配置更加透明。
:::
用户宏可用于：
- 监控项名称
- 监控项键参数
- 监控项update间隔和灵活间隔
- 触发器名称和描述
- 触发器表达式参数和常量（参见[示例](#examples)）
- 许多其他位置 - 详见[full
list](/manual/appendix/macros/supported_by_location_user)
[comment]: # ({/c282a934-3e220640})
[comment]: # ({e3755145-e3755145})
##### 全局宏与主机宏的常见应用场景
- 在多个位置使用全局宏；然后更改宏的值，并通过一次点击将配置更改应用到所有位置
- 利用带有主机特定属性的模板：密码、端口号、file名称、正则表达式等
[comment]: # ({/e3755145-e3755145})
[comment]: # ({be6c0958-60e46db2})
::: notetip
建议使用 主机宏 而不是全局宏，因为添加、更新或删除全局宏会强制对所有 主机 进行增量配置 update。有关更多信息，请参见 [主动检查](/manual/appendix/items/activepassive#主动检查)。
:::
[comment]: # ({/be6c0958-60e46db2})
[comment]: # ({808a388a-561314a3})
#### 配置
要定义用户宏，请转到前端中的相应位置：
- 对于全局宏，访问 *Administration → Macros*
- 对于主机和模板级别的宏，打开主机或模板属性
并查找 *Macros* 选项卡
用户宏具有以下属性：
{width="600"}
|Parameter|Description|
|--|--------|
|*Macro*|宏名称。名称必须用花括号括起来，并以美元符号开头。
示例：{$FRONTEND\_URL}。宏名称中允许使用以下字符：**A-Z**（仅大写） 、**0-9** 、**\_** 、**.**|
|*Value*|宏值。支持三种值类型：
**Text**（默认）- 纯文本值
**[Secret text](/manual/config/macros/secret_macros#secret-text)** - 值会以星号掩码显示
**[Vault secret](/manual/config/macros/secret_macros#vault-secret)** - 值包含指向 [vault secret](/manual/config/secrets) 的路径/查询。
要更改值类型，请单击值输入字段末尾的按钮。
用户宏值的最大长度为 2048 个字符。|
|*Description*|用于提供有关此宏更多信息的文本字段。|
配置用户宏时，**请注意**以下与上下文相关的行为：
- 如果在模板监控项或触发器中使用了用户宏，请考虑将这些宏也添加到模板中（即使它们已在全局定义）；这样，在将模板导出为 XML 并导入到其他系统后，*Text* 类型宏仍可按预期工作（密文宏值不会被 [导出](/manual/xml_export_import)）
- 如果在触发器表达式中使用了用户宏，则这些宏只有在引用参数或常量时才会解析；如果引用主机、监控项键值、函数、运算符或其他触发器表达式，则不会解析（密文宏不能用于触发器表达式）
- 如果在具有低级别发现规则和主机原型的主机上使用了用户宏，[发现的主机](/manual/discovery/low_level_discovery/host_prototypes#discovered-hosts) 将继承该主机上定义的所有用户宏
[comment]: # ({/808a388a-561314a3})
[comment]: # ({4c860844-4c860844})
#### 示例
[comment]: # ({/4c860844-4c860844})
[comment]: # ({b9cf8f56-b9cf8f56})
##### 示例1
在“SSH守护进程状态”监控项键中使用主机级别宏：
net.tcp.service[ssh,,{$SSH_PORT}]
该 监控项 可以分配给多个 主机，前提是其值为
**{$SSH\_PORT}** 在这些 主机 上定义。
[comment]: # ({/b9cf8f56-b9cf8f56})
[comment]: # ({0fa7cf4a-0fa7cf4a})
##### 示例2
在“CPU负载过高”触发器中使用主机级别宏：
`last(/ca_001/system.cpu.load[,avg1])>{$MAX_CPULOAD}`
此类触发器将在模板上创建，而不是在各个主机中进行编辑。
::: notetip
如果您希望使用值的数量作为函数参数（例如，**max(/主机/key,\#3)**），请在宏定义中包含井号，如下所示：SOME\_PERIOD => \#3
:::
[comment]: # ({/0fa7cf4a-0fa7cf4a})
[comment]: # ({36dc94ca-36dc94ca})
##### 示例3
在“CPU负载过高”触发器中使用两个宏：
`min(/ca_001/system.cpu.load[,avg1],{$CPULOAD_PERIOD})>{$MAX_CPULOAD}`
请注意，宏可以用作触发器函数的参数，在
此示例中为函数 **min()**。
[comment]: # ({/36dc94ca-36dc94ca})
[comment]: # ({0dabfae5-0dabfae5})
##### 示例4
将 agent 不可用条件与 监控项 update 间隔同步：
- 定义 {$INTERVAL} 宏，并在 监控项 update 间隔中使用它；
- 使用 {$INTERVAL} 作为 agent 不可用触发器的参数：
`nodata(/ca_001/agent.ping,{$INTERVAL})=1`
[comment]: # ({/0dabfae5-0dabfae5})
[comment]: # ({2d346656-0f8052f1})
##### 示例5
集中配置工作时间：
- create 一个全局的 {$WORKING\_HOURS} 宏，其值等于 `1-5,09:00-18:00`；
- 在 *Administration* → *General* → *GUI* 中的 *Working time* 字段中使用它；
- 在 *Users* → *Users* 中用户的 *Media* 标签页的 *When active* 字段中使用它；
- 在设置工作时间内的更频繁的 监控项 轮询时使用它：
- 在 *Time period* 动作条件中使用它；
- 如有需要，在 *Administration* → *Macros* 中调整工作时间。
[comment]: # ({/2d346656-0f8052f1})
[comment]: # ({3c2ac944-3c2ac944})
##### 示例6
使用 主机 原型宏来为发现的 主机 配置 监控项：
- 在 一个主机 原型上定义用户宏 {$SNMPVALUE}
使用{\#SNMPVALUE} [low-level
discovery](/manual/config/macros/lld_macros)宏作为值：
- 将 *Generic SNMPv2* 模板分配给 主机 原型；
- 在 *Generic SNMPv2* 的 *SNMP OID* 字段中使用 {$SNMPVALUE}
模板 监控项。
[comment]: # ({/3c2ac944-3c2ac944})
[comment]: # ({44ca625a-44ca625a})
#### 用户宏上下文
参见 [user macros with
context](/manual/config/macros/user_macros_context)。
[comment]: # ({/44ca625a-44ca625a})