x/snmpRead 组件：v0.37.0+ 用于通过 SNMP 协议（v1/v2c/v3）批量读取网络/设施设备（交换机/路由器/UPS/传感器等）的 OID 数据。

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

配置

字段	类型	说明	默认值
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）：

字段	类型	说明	默认值
name	string	点位名称，用于结果标识	无
addr	string	SNMP OID，如 1.3.6.1.2.1.1.5.0；加 walk: 前缀（大小写不敏感，如 walk:1.3.6.1.2.1.2.2.1.10）表示遍历子树，可能返回多条数据；无前缀为 Get	无
scale	float	可选，缩放系数，换算公式 eng = raw*scale + offset	1
offset	float	可选，偏移量	0

所有字段均支持 ${msg.xx} / ${metadata.xx} 模板变量。type/value 字段为写节点专用，读节点不使用。

输出

读取结果（统一契约 Data 列表）写回 msg.Data，dataType 置为 JSON。格式：

[
  {
    "name": "sysName",
    "address": "1.3.6.1.2.1.1.5.0",
    "value": "router-01",
    "type": "OctetString",
    "quality": "good",
    "timestamp": "2026-07-23T10:00:00.123Z"
  }
]

字段	类型	说明
name	string	点位名称（来自配置）
address	string	实际返回的 OID（当 addr 带 walk: 前缀时为子树下具体节点）
value	any	值，类型由 SNMP PDU 类型决定
type	string	SNMP 类型字符串：Integer/OctetString/ObjectIdentifier/IPAddress/Counter32/Gauge32/TimeTicks/Counter64/Null
quality	string	数据质量：good（成功）/ bad（失败）
timestamp	string	采集时间戳（RFC3339 格式）

带 walk: 前缀的点位可能返回多条数据；单个点位失败不影响其它点位（标记 quality=bad）。仅当全部点位都失败（疑似连接级错误）时才触发重连重试。

特性

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

Relation Type

• Success: 读取成功，把消息发送到 Success 链。
• Failure: 读取失败，把消息发送到 Failure 链。

示例

{
  "ruleChain": {
    "name": "snmp read demo",
    "root": true
  },
  "metadata": {
    "nodes": [
      {
        "type": "x/snmpRead",
        "name": "读取设备信息",
        "configuration": {
          "server": "192.168.1.1:161",
          "version": "v2c",
          "community": "public",
          "timeout": 5,
          "points": [
            { "name": "sysName", "addr": "1.3.6.1.2.1.1.5.0" },
            { "name": "ifInOctets", "addr": "walk:1.3.6.1.2.1.2.2.1.10" }
          ]
        }
      }
    ]
  }
}

SNMPv3 示例配置片段：

{
  "server": "192.168.1.1:161",
  "version": "v3",
  "timeout": 5,
  "securityLevel": "authPriv",
  "username": "admin",
  "authProtocol": "SHA",
  "authPassword": "authPass",
  "privProtocol": "AES",
  "privPassword": "privPass",
  "points": [
    { "name": "sysUpTime", "addr": "1.3.6.1.2.1.1.3.0" }
  ]
}