[comment]: # translation:outdated
[comment]: # ({d30dc182-d30dc182})
# 2 用户宏
[comment]: # ({/d30dc182-d30dc182})
[comment]: # ({c282a934-3e220640})
#### 概述
除了开箱即用的宏[支持](/manual/appendix/macros/supported_by_location)之外，Zabbix还支持用户宏，以提高灵活性。
用户宏可以在全局、模板和主机级别定义。这些宏有一种特殊的语法：
{$MACRO}
Zabbix根据以下优先级解析宏：
1.主机级宏（先选中）
2.为主机的一级模板（即直接链接到主机的模板）定义的宏，按模板ID排序
3.为主机二级模板定义的宏，按模板ID排序
4.为主机的三级模板定义的宏，按模板ID等排序。
5.全局宏（最后选中）
换句话说，如果主机不存在宏，Zabbix将尝试在深度不断增加的主机模板中找到它。如果仍然找不到，将使用全局宏（如果存在）。
::: notewarning
如果同一级别的多个链接模板上存在具有**相同名称**的宏，则将使用ID最低的模板中的宏。因此，在多个模板中使用相同名称的宏是一种配置风险。
:::
如果Zabbix找不到宏，宏将无法解析。
::: noteimportant
宏（包括用户宏）在配置部分（例如，在触发器列表中）被设计为不可解析，以使复杂的配置更加透明。
:::
用户宏可用于：
- 监控项名称
- 监控项key参数
- 监控项更新间隔和灵活间隔
- 触发器名称和描述
- 触发器表达式参数和常量(参见[示例](#示例))
- 许多其他位置-请参阅[完整列表](/manual/appendix/macros/supported_by_location_user)
[comment]: # ({/c282a934-3e220640})
[comment]: # ({e3755145-e3755145})
##### 全局和宿主宏的常见用例
- 在多个位置使用全局宏；然后更改宏值并一键将配置更改应用于所有位置
- 利用具有主机特定属性的模板：密码、端口号、文件名、正则表达式等。
[comment]: # ({/e3755145-e3755145})
[comment]: # ({be6c0958-60e46db2})
::: notetip
建议使用主机宏而不是全局宏，因为添加、更新或删除全局宏会导致所有主机进行增量配置更新。更多信息，请参阅相关文档。[被动和主动agent检查](/manual/appendix/items/activepassive#active-checks)。
:::
[comment]: # ({/be6c0958-60e46db2})
[comment]: # ({60595cde-561314a3})
#### 配置
要定义用户宏，请转到前端中的相应位置：
- 有关全局宏，请访问*管理→ 宏*
- 对于主机和模板级宏，请打开主机或模板属性，然后查找*macros*选项卡
::: notetip
如果用户宏用于模板中的监控项或触发器，建议将该宏添加到模板中，即使该宏是在全局级别定义的。这样，如果宏类型为*text*，则将模板导出为XML并将其导入另一个系统仍将允许其按预期工作。加密宏的值不会[导出](/manual/xml\u export\u import)。
:::
用户宏具有以下属性：
{width=“600”}
|参数|描述|
|---------|-----------|
|*宏*|宏名称。名字必须用花括号括起来，并以美元符号开头
示例：{$FRONTEND\_URL}。宏名称中允许使用以下字符：**A-Z**(仅大写)，**0-9**，**\_**，**.**|
|*Value*|宏值。支持三种值类型：
**文本** (默认) - 普通文本值
**[Secret text](/manual/config/macros/secret_macros#secret_text)** - 值被星号遮蔽
**[Vault secret](/manual/config/macros/secret_macros#vault_secret)** - 值包含指向 [vault secret](/manual/config/secrets)的路径/查询。
要更改值类型，请单击值输入字段末尾的按钮。
用户宏值的最大长度为 2048 个字符。|
|*描述*|文本字段用于提供关于此宏的更多信息。|
:::noteclassic
包含秘密宏的URLs将无法工作，因为其中的宏将解析为“\*\*\*\*\*\*\*”。
:::
::: noteimportant
在触发器表达式中，用户宏将解析是否引用参数或常量。如果引用主机、监控项键、函数、运算符或其他触发器表达式，则它们将不会解析。不能在触发器表达式中使用加密宏。
:::
[comment]: # ({/60595cde-561314a3})
[comment]: # ({4c860844-4c860844})
#### 示例
[comment]: # ({/4c860844-4c860844})
[comment]: # ({b9cf8f56-b9cf8f56})
##### 示例 1
在“SSH daemon 状态”项键中使用主机级宏：`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(/host/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不可用条件与监控项更新同步间隔：
- 定义 {$INTERVAL} 宏并在监控项更新间隔中使用它；
- 使用 {$INTERVAL} 作为agent不可用触发器的参数：
`nodata(/ca_001/agent.ping,{$INTERVAL})=1`
[comment]: # ({/0dabfae5-0dabfae5})
[comment]: # ({2d346656-0f8052f1})
##### 示例 5
集中配置工作时间：
- 创建一个全局 {$WORKING\_HOURS} 宏，等于 `1-5,09:00-18:00`；
- 在 *Administration* → *General* → *Working time* 字段中使用它 *图形界面*；
- 在 *User* → *Users* ，用户的_媒体_ 页签中的_当激活_ 字段使用；
- 使用它在工作时间设置更频繁的监控项轮询：
- 在*时间段*动作条件下使用；
- 在 *Administration* → *General* → *Macros* 中调整工作时间， 如果需要的话。
[comment]: # ({/2d346656-0f8052f1})
[comment]: # ({3c2ac944-3c2ac944})
##### 示例 6
使用主机原型宏为发现的主机配置监控项：
- 在主机原型上定义用户宏 {$SNMPVALUE}和{\#SNMPVALUE} [低级别自动发现](/manual/config/macros/lld_macros) 宏作为值：
- 将 *Generic SNMPv2* 模板分配给主机原型；
- 在 *Generic SNMPv2* 的 *SNMP OID* 字段中使用 {$SNMPVALUE} 模板项。
[comment]: # ({/3c2ac944-3c2ac944})
[comment]: # ({44ca625a-44ca625a})
#### 用户宏语境
请参阅 [带语境的用户宏](/manual/config/macros/user_macros_context)。
[comment]: # ({/44ca625a-44ca625a})