工业设备数据API接入实战:登录、点表、实时快照三个请求
适合读者:前后端开发者、工业应用研发人员。
读完可以做什么:按三个请求读取设备数据,并把数值、时间、质量和异常状态映射成应用卡片。
IndustrialSphere开发实战 · 第1篇,共3篇
你已经会做业务页面、调用HTTP接口,准备给应用加一张设备温度卡片。设备来自PLC,是否必须先从通讯驱动写起?当EdgeHub已完成设备接入后,可以先通过登录、点位查询和快照读取三个请求,拿到应用所需的数据。
这篇文章的目标很具体:让卡片显示数值、单位和时间,并在数据不可用时给出正确提示。下面使用当前EdgeHub接口,实际点位和访问地址按测试环境配置。
准备一个可以核对的点位
先在EdgeHub中配置并启用一个测试变量,确认网关页面能够读取它。本文用名称Demo_Temperature表示温度变量,该名称不会由接口自动创建。
对接前记录它的数据类型、单位和设备来源。可以使用模拟设备或受控测试设备,使数值变化能够被重复观察。接口客户端与网关应具备已确认的网络访问条件,正式部署使用配置好证书的HTTPS。
第一步:取得登录令牌

图:三类请求分别完成认证、点位确认和快照读取,页面保留点位时间与异常状态。图示为说明示例。
在API调试工具中,向自己的EdgeHub服务发送以下请求。示例中的双花括号表示调试工具的本地环境变量,应先配置实际值,不要直接发送占位文字。
POST /User/Login
Content-Type: application/json
{"username":"{{username}}","password":"{{password}}"}
登录成功后,从响应的data.token读取令牌,在后续请求头中使用Authorization: Bearer {{token}}。首次密码修改等账号设置应先按界面流程完成。
密码和令牌保存在本地调试环境或服务端受控配置中,不放进公开页面、代码仓库或文章截图。应用遇到401时应处理会话失效,不要在每个刷新周期反复提交账号密码。
第二步:确认真实点位名称
GET /api/v1/edgehub/metadata/tags?pageIndex=1&pageSize=50
Authorization: Bearer {{token}}
响应包含items与total等分页信息。每个点位可以查看tagName、deviceName、dataType、unit、active、archive、readable和writable等字段。
使用返回的tagName发起后续请求,不要把画面显示文字或设备地址直接当作变量名称。列表超过一页时继续分页查询,不能把第一页理解成全部点位。
第三步:读取当前快照
POST /api/v1/edgehub/tags/snapshot
Authorization: Bearer {{token}}
Content-Type: application/json
{"tagNames":["Demo_Temperature"]}
返回的snapshotAt表示快照响应时间,results包含各点位结果。重点检查以下字段:
| 字段 | 使用方式 |
|---|---|
| tagName | 对应本次请求的变量 |
| success | 该点位本次读取结果是否可用 |
| value | 点位值;按实际数据类型解释 |
| quality | 点位质量,不应丢弃 |
| timestamp | 点位自身的数据时间 |
| error | 不存在、未启用或质量异常等原因 |
value采用字符串表达时,业务端应按元数据转换。不要把空字符串转换为数字零,也不要把字符串"false"直接按非空字符串判断为真。
把响应转换成读者看得懂的卡片
下面是用于解释字段的响应节选示例,数值和时间为示意,并非现场实测记录:
{
"snapshotAt": "2026-11-16T00:00:02Z",
"results": [
{
"tagName": "Demo_Temperature",
"success": true,
"value": "26.5",
"quality": 192,
"timestamp": "2026-11-16T00:00:00Z",
"error": ""
}
]
}
若元数据中的单位为℃,页面按UTC+8显示时,卡片可以显示“26.5 ℃”,并注明数据时间08:00:00。08:00:02是转换到同一时区后的快照时间,不能用它覆盖点位的数据时间;应用还应按本项目的采集方式判断新鲜度。
下一次查询如果该项success为假,应显示异常原因;即使value仍有内容,也不能直接维持绿色正常状态。若收到401,则显示登录失效,进入应用的重新认证流程。这两种异常分别对应数据问题和访问问题。
这个映射可以由你的后端或页面实现。IndustrialSphere提供设备侧数据出口,你继续沿用自己的前端框架和页面设计。
快照读取与现场读取有什么区别
tags/snapshot读取网关当前持有的数据,不会因为调用一次就主动访问一次PLC。设备采集周期与页面刷新周期是两个概念,提高页面刷新频率不等于提高现场采样频率。
需要明确发起设备读取时,平台另有realtime/read-from-driver接口,需要提供驱动与变量信息。是否使用它,应根据调试需求和现场通讯负载决定;普通展示页面通常先采用快照方式。
请求多个点位时,要逐项检查results。HTTP 200只表示请求得到了正常响应,不保证每个点位都有效。当前快照接口单次最多请求200个点位,大规模读取需规划分批和频率。
做一个有异常状态的数据卡片
自己的页面可以先实现四种状态:加载中、正常数值、数据异常、访问失败。正常状态显示单位和更新时间;异常状态保留必要说明,避免继续用绿色数字表示设备正常。
验证时改变测试点位数值,再停用变量或中断测试通讯,检查页面能否区分这些情况。令牌失效时,也应显示访问问题,而非设备停机。
完成这些检查后,一个点位已经具备可解释的读取链路。后续增加设备列表、趋势或业务关联,就有了明确的数据基础。
延伸阅读与交流
下一篇:用设备历史数据制作趋势页面。EdgeHub介绍提供产品背景。
可以先用这三个请求接一个测试点位,再把响应映射成自己的卡片。遇到问题时,欢迎带上脱敏后的请求路径、状态码和点位结果,到IndustrialSphere技术交流群(QQ群:1128988613)交流;不要携带密码或令牌。
浙公网安备 33010602011771号