4.3 实时数据接口

通过 POST /web 读写实时数据库的数据点，以及直读直写在线 PLC 的寄存器。所有请求都要带 username/password，操作名放在 cmd 字段（详见 4.1）。

高频刷新用 WebSocket / MQTT

HTTP 接口适合按需读写、批量操作、后台程序对接。要持续接收数据点变化，用 WebSocket（项目变量）或 MQTT 订阅，不要循环轮询 HTTP。

4.3.1 读取指定数据点：get_real

一次读取若干个已知名字的数据点。

请求：

{
  "cmd": "get_real",
  "username": "linpan",
  "password": "你的密码",
  "project": "main",
  "data": ["车间1/1号机/温度", "车间1/1号机/湿度"]
}

data 是数据点名数组；project 省略时默认 main。

响应：

{
  "cmdreq": "ok",
  "data": [
    { "name": "车间1/1号机/温度", "value": "25.6" },
    { "name": "车间1/1号机/湿度", "value": "60" }
  ]
}

get_real 返回的 value 一律是字符串（"25.6" 而不是 25.6），数值要先转换再用。数据点不存在时对应 value 为空。

注意区分：本接口的值是字符串，而 4.3.6 的 plc_data_read 直接返回数字。两个接口的取值写法不一样。

4.3.2 写入数据点：set_real

批量写入。数据点不存在会自动创建。

请求：

{
  "cmd": "set_real",
  "username": "linpan",
  "password": "你的密码",
  "userson": "backend01",
  "client": "MES",
  "project": "main",
  "data": [
    { "name": "车间1/1号机/启停", "value": "1" },
    { "name": "车间1/1号机/设定温度", "value": "80" }
  ]
}

• data 是 {name, value} 数组
• userson、client 可选，仅用于操作日志记录（谁、通过什么平台改的）
• 写入会被记入操作日志，可追溯

响应：{ "cmdreq": "ok" }

写入后，订阅了对应主题的 MQTT 设备会收到下发，绑定了该数据点的云组态画面会刷新。这就是从后台程序远程控制设备的方式：写数据点 → 服务器下发 → 设备执行。

4.3.3 分页列出全部数据点：get_real_list

不知道有哪些点时，分页拉整个项目的数据点。

{
  "cmd": "get_real_list",
  "username": "linpan",
  "password": "你的密码",
  "project": "main",
  "limit": 100,
  "offset": 0
}

响应带 data 数组、limit、offset；当 offset 为 0 时额外返回 total（数据点总数）。翻页把 offset 累加。取到 noMore 表示到底了。

4.3.4 关键字查询：get_real_select

按名字模糊搜索。

{
  "cmd": "get_real_select",
  "username": "linpan",
  "password": "你的密码",
  "project": "main",
  "keyword": "温度"
}

响应结构同 get_real_list 的 data。

4.3.5 删除与改名

删除一个点：

{ "cmd": "del_real", "username": "...", "password": "...",
  "project": "main", "data": { "name": "车间1/1号机/温度" } }

改名（历史数据一并迁移）：

{ "cmd": "real_replace", "username": "...", "password": "...",
  "data": { "project": "main", "name_old": "旧名", "name_new": "新名" } }

4.3.6 直读直写 PLC 寄存器：plc_data_read / plc_data_write

不经过实时数据库，直接读写某台在线 PLC 的寄存器。对应云组态里的 @设备ID.寄存器（见 3.4）。

读寄存器：

{
  "cmd": "plc_data_read",
  "username": "linpan",
  "password": "你的密码",
  "id": "11315751",
  "reg": "D0",
  "type": 1,
  "length": 7
}

• id：目标设备 ID，必填，缺失返回 no id
• reg：起始寄存器，如 D0、Y0、M100
• type：数据类型编号（见下表）
• length：连续读取的数量，一次读回 reg 起 length 个

写寄存器：

{
  "cmd": "plc_data_write",
  "username": "linpan",
  "password": "你的密码",
  "id": "11315751",
  "reg": "Y0",
  "type": 0,
  "value": 1
}

数据类型编号：

type	含义	适用寄存器
0	位	X / Y / M / S
1	16 位有符号整数	D / T / C（C0-C199）
2	32 位有符号整数	D / C（C200-C255）
3	单精度浮点	D
4	双精度浮点	D

读响应（data 为 {reg, value} 数组）：

{
  "cmdreq": "ok",
  "data": [
    { "reg": "D0", "value": 25 },
    { "reg": "D1", "value": 130 }
  ]
}

这里的 value 是数字（不是字符串），按上面的 type 决定是 0/1、整数还是浮点数。

设备不在线时返回 no id。X/Y 编号按八进制，与云组态设备变量一致。

4.3.7 该用哪个接口

需求	接口
读/写云端数据点（MQTT、DTU、脚本上报的数据）	get_real / set_real
远程控制设备（写数据点触发下发）	set_real
不知道有哪些点，先列出来	get_real_list / get_real_select
直接读写某台 PLC 的寄存器，不落库	plc_data_read / plc_data_write
持续接收变化	WebSocket / MQTT，不要轮询本接口

---