IndustrialSphere Industrial Data · Edge · SCADA · IoT

工业设备数据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)交流;不要携带密码或令牌。

继续解决相关问题

posted @ 2026-11-16 23:11  IndustrialSphere  阅读(0)  评论(0)    收藏  举报