[comment]: # ({d30dc182-d30dc182})
# 2 用户宏
[comment]: # ({/d30dc182-d30dc182})
[comment]: # ({3e220640-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]: # ({/3e220640-3e220640})
[comment]: # ({e3755145-e3755145})
##### 全局宏与主机宏的常见应用场景
- 在多个位置使用全局宏；然后更改宏值并通过一次点击将配置更改应用到所有位置
- 利用具有主机特定属性的模板：
密码、端口号、file名称、正则表达式等
[comment]: # ({/e3755145-e3755145})
[comment]: # ({1814b616-561314a3})
#### 配置
要定义用户宏，请在前端相应位置进行操作：
- 全局宏请访问*管理 → 常规 → 宏*
- 主机和模板级宏需打开主机或模板属性
and look for the *Macros* tab
::: notetip
如果在模板的监控项或触发器中使用了用户宏，
建议将该宏添加到模板中——即使已在全局层面定义。
这样当宏类型为*文本*时，将模板导出为XML并导入其他系统后，
仍能按预期工作。秘密宏的值不会被[exported](/manual/xml_export_import)。
:::
用户宏具有以下属性：
{width="600"}
| 参数 | 描述 |
|--|--------|
| *Macro* | 宏名称。名称必须用花括号包裹并以美元符号开头。
示例：{$FRONTEND\_URL}。宏名称允许以下字符：**A-Z**（仅大写）、**0-9**、**\_**、**.** |
| *Value* | 宏值。支持三种值类型：
**文本**（默认）- 纯文本值
**秘密文本** - 值以星号掩码显示，适用于保护密码或共享密钥等敏感信息
**Vault机密** - 值包含指向[Vault secret](/manual/config/secrets)的引用路径（格式如'path:key'，例如"secret/zabbix:password"）
*注意*：虽然秘密宏的值不可见，但通过监控项的使用可能暴露其值。例如在外部脚本中，引用秘密宏的'echo'语句可能将宏值暴露给前端，因为Zabbix server有权访问真实的宏值。
点击值输入字段末端的按钮选择值类型：
图标表示文本宏；
图标表示秘密文本宏。悬停时值字段会变为按钮，可输入新宏值（要退出而不保存新值，点击后退箭头）；
图标表示Vault机密宏。
用户宏值的最大长度为2048字符（5.2.0之前版本为255字符）。 |
| *Description* | 用于提供该宏更多信息的文本字段。 |
::: noteclassic
包含秘密宏的URL将无法正常工作，
因为其中的宏会被解析为"\*\*\*\*\*\*"。
:::
::: noteimportant
在触发器表达式中，用户宏仅在引用参数或常量时会被解析。
引用一个主机、监控项键、函数、运算符或其他触发器表达式时不会被解析。
秘密宏不能用于触发器表达式。
:::
[comment]: # ({/1814b616-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]: # ({494029cf-0f8052f1})
##### 示例5
集中配置工作时间:
- create 全局宏 {$WORKING\_HOURS} 等于 `1-5,09:00-18:00`;
- 在*管理* → *常规* → *工作时间*字段中使用它
*GUI*;
- 在*Administration* → *Users* → *When active*字段中使用它
*媒体*;
- 使用它来在工作时间内设置更频繁的监控项轮询:
- 在*时间段*操作条件中使用它;
- 在*管理* → *通用* → *宏*中调整工作时间,
如果需要。
[comment]: # ({/494029cf-0f8052f1})
[comment]: # ({3c2ac944-3c2ac944})
##### 示例6
使用主机原型宏为发现的主机配置监控项:
- 在一个主机原型上定义用户宏{$SNMPVALUE}并设置
{\#SNMPVALUE} [low-level
discovery](/manual/config/macros/lld_macros) macro as a value:
- 将*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})