x/snmpWrite 组件：v0.37.0+ 用于通过 SNMP 协议（v1/v2c/v3）向网络/设施设备（交换机/路由器/UPS/传感器等）写入（Set）OID 值。

需要额外引入扩展库： rulego-components-iot (opens new window)

配置

连接配置与 x/snmpRead 完全一致，此处列出全部字段：

字段	类型	说明	默认值
server	string	设备地址（host 或 host:port，默认端口 161）	127.0.0.1:161
version	string	SNMP 版本，可选值：v1/v2c/v3	v2c
community	string	community 字符串（v1/v2c 使用）	public
timeout	int	请求超时时间（秒）	5
v3 安全参数		以下字段仅 version=v3 时使用，对应 SNMPv3 USM 安全模型
securityLevel	string	安全级别，可选值：noAuthNoPriv/authNoPriv/authPriv	noAuthNoPriv
username	string	v3 用户名	无
authProtocol	string	认证协议，可选值：None/MD5/SHA/SHA224/SHA256/SHA384/SHA512	None
authPassword	string	认证密码	无
privProtocol	string	加密协议，可选值：None/DES/AES/AES192/AES256	None
privPassword	string	加密密码	无
points		默认点位表
points	[]Point	默认写入点位列表；当 msg.Data 携带合法点位时优先使用 msg.Data	无

点位(Point)字段说明

每个 Point 的字段（写节点使用 name/addr/type/value）：

字段	类型	说明	默认值
name	string	点位名称（可选）	无
addr	string	待写入的 SNMP OID，例如 1.3.6.1.2.1.1.5.0	无
type	string	值类型，必填，可选值见下表	无
value	string	值的字符串形式，支持 ${msg.xx} 占位符	无
scale	float	可选，缩放系数，换算公式 eng = raw*scale + offset	1
offset	float	可选，偏移量	0

type 可选值（写入值类型）：

type	说明	别名
Integer	整数	integer、int
OctetString	字节串/字符串	octetstring、string
ObjectIdentifier	OID	objectidentifier、oid
IPAddress	IP 地址	ipaddress、ip
Counter32	32 位计数器	-
Gauge32	32 位度量	gauge32、uint32
TimeTicks	时间滴答	timeticks
Counter64	64 位计数器	counter64

输入

写入点位从 msg.Data 读取（JSON 数组）。若 msg.Data 为空则使用配置的 points。格式：

[
  { "addr": "1.3.6.1.2.1.1.5.0", "type": "OctetString", "value": "router-01" },
  { "addr": "1.3.6.1.2.1.1.6.0", "type": "OctetString", "value": "${msg.location}" }
]

value 支持 ${msg.xx} / ${metadata.xx} 模板变量。任一点位写入失败立即返回错误（不继续后续点位）。

特性

• 模板变量：点位的 addr/type/value 字段支持 ${msg.xx} / ${metadata.xx} 占位符。
• 动态点位：msg.Data 携带合法点位列表（JSON 数组）时优先使用，适合运行时动态决定写入点位的场景。
• 同链连接池：启用 ref:// 同链连接复用，链内其它节点可按节点 ID 借用连接，避免重复建连。参考组件连接复用。
• 自动重连重试：写入失败自动重建连接并重试，最多 3 次（maxRetries=3）。
• SNMPv3 USM：完整支持 v3 User Security Model（认证 + 加密）。

Relation Type

• Success: 写入成功，把消息发送到 Success 链（不改变消息负荷值）。
• Failure: 写入失败，把消息发送到 Failure 链。

示例

{
  "ruleChain": {
    "name": "snmp write demo",
    "root": true
  },
  "metadata": {
    "nodes": [
      {
        "type": "x/snmpWrite",
        "name": "写入设备配置",
        "configuration": {
          "server": "192.168.1.1:161",
          "version": "v2c",
          "community": "private",
          "timeout": 5,
          "points": [
            { "name": "sysName", "addr": "1.3.6.1.2.1.1.5.0", "type": "OctetString", "value": "core-switch-01" },
            { "name": "sysLocation", "addr": "1.3.6.1.2.1.1.6.0", "type": "OctetString", "value": "${msg.location}" }
          ]
        }
      }
    ]
  }
}