跳到主要内容

WebAPI接口说明

当企业自有平台或者第三方的平台系统(统称为第三方平台)需要与海为物联终端设备进行数据实时读写时,除了 MQTT 协议之外,还可以选择使用 Web Api 功能与设备实现数据交互,使用标准 HTTP POST 请求,包括支持 PHP、C#、Java、Go、Nodejs 等开发语言。


基本原理

Web Api 实现的基本原理,是通过在物联终端(HMI/BOX 等)的工程中的数据组来实现的,实现功能包括:

  • 主动推送:数据组中可以选择将数据组的通道变量上报给指定的 URL 路径(URL 路径也可以通过 API 进行动态设置),可指定推送时机,包括有定时推送、间隔推送、触发推送、变动推送等,当推送时机触发时,会主动向指定的 URL 发送 Post 请求,请求中包括整个数据组的通道变量值;

  • 接口调用:通过本文档规定的 Api 进行数据的读取和写入,但是只能读取数据组中的通道变量值,也只能写入数据组中勾选允许远程写入的通道,以提高远程操作安全性。


工程配置

1. 数据上报服务器配置

如上图可以获取 Web API 的私钥,在接口调用中需要用到;上图中的 API 主路径,可以通过 API 接口进行动态切换,以满足用户批量设备用于不同项目的需求。

2. 数据组配置

每个数据组可以定义一组的变量往一个第三方平台的 API 上报,支持多种上报时机选择,注意配置其中的通道标识,在接口调用中需要用到,其中的“允许远程写入”决定了接口是否可以写入该变量通道

主动推送

由第三方平台提供一个接收 POST 请求的 API,支持 HTTP 和 HTTPS,将该 API 的 URL 设置到工程中的数据上报服务器中,如果有多个接口需要接收主动推送的不同数据,则可以设置多个数据组分别上报给不同的接口,为了方便 URL 的配置和修改,支持只在数据上报服务器中设置主路径,在具体的数据组中设置子路径,在主动推送时,设备端会将主路径与子路径拼接后进行推送。

为了数据的安全不被随意截获,推送的数据支持加密后发送(需要在数据组中配置为加密模式),第三方需要进行解密,解密算法见本文档最后章节说明,当然也可以不选加密模式,则明文推送。

推送的格式为:
{
"_terminalTime": "2018-01-01 06:30:30",
"_groupTag": "my_group_tag",
"Y0": "1",
"V0": "99"
}

内容格式是json,其中_terminalTime由物联终端在上报时自动生成,它表示上报的设备端时间。_groupTag也是由物联终端自动加入,它表示数据组标识。

注意

为方便处理,json 中所有条目的数据格式都是字符串。你可以看到,虽然 V0 变量是整型,但是在 json 中的数据格式是字符串。

接口调用方式

1. 局域网接口调用

如果企业内部的系统需要对设备进行数据交互,可选择使用局域网接口调用方式。

在局域网模式下,走 http 通道,为了安全,除了数据进行加密之外,还必须对 api 请求时效进行验证,时效是基于设备端的时间为基准进行对比,所以要先获取设备端的时间,然后在参数中有 timeout 属性进行时效对比,超出时效将拒绝响应,以提高安全性。

2.互联网接口调用

在互联网环境下,要读取或者写入设备的值,需要通过海为云服务器进行交互,所以需要调用海为云接口,为了安全,接口强制走 https 安全协议,由于数据传输的安全性由 https 协议保证,所以该模式下,不需要进行数据加密,也不需要进行时效验证,但还是需要进行接口鉴权,鉴权方式与画面集成接口的鉴权方式一致,即通过云数据中心进行鉴权。

  1. 登录个人云网站,在云数据中心,将需要使用 webapi 功能的设备添加到项目中。

  2. 记录云网站的登录账号、云数据中心的项目私钥、该项目下对应需要画面集成的设备 PN 码。

  1. 按照互联网读取或写入数据的 API 规范方式请求接口,即可获取对设备进行数据交互,注意接口即有云数据中心的项目私钥,也要有工程中配置的 Web API 私钥。

API 说明

互联网读取设备数据

  • API:
接口https://cloud.haiwell.com/api/project/machine/datagroup/getTagsValue
方法POST
作用读取设备数据组中通道变量的值
  • 参数:
字段必填描述备注
account账号手机号或邮箱
machineCode机器码 PN
privateKey云数据中心项目私钥
webapiKeyWebApi 私钥
groupTag数据组标识
tags通道数组["SL","JE"]
示例
{
"account": "133xxxxxxxx",
"machineCode": "53513186496xxxxxxxx",
"privateKey": "f6e08a8cf377b09exxxx",
"webapiKey": "42410d0cd723xxxx",
"groupTag": "group1",
"tags": ["W0", "B0", "Second"]
}
返回值:
Success:
"result": {
"code": 1, // 0:有失败,1:全部成功
"data": {
"SL": "10",
"JE": "68.96"
}
}

Error:
"error": {
"code":08012101
}

error.code:
08012101:参数不足
0801000108010002: 设备不存在或云服务器不存在
08012102:私钥不正确
08012103:解密失败
08012104:超时过期
0801000308012105:操作失败
08012106:与设备通信失败

互联网写入设备数据

  • API:
接口https://cloud.haiwell.com/api/project/machine/datagroup/setTagsValue
方法POST
作用设置数据组中的通道变量的值
  • 参数:
字段必填描述备注
account账号手机号或邮箱
machineCode机器码 PN
privateKey云数据中心项目私钥
webapiKeyWebApi 私钥
groupTag数据组标识
tags变量通道标识和值列表{"SL":"1","JE":"2"}
示例
{
"account": "133xxxxxxxx",
"machineCode": "53513186496xxxxxxxx",
"privateKey": "f6e08a8cf377b09exxxx",
"webapiKey": "42410d0cd723xxxx",
"groupTag": "group1",
"tags": { "W0": "123", "B0": "1" }
}
返回值:
Success:
"result": {
"code": 0, // 0:有失败,1:全部成功
"data": {
"SL": 1, // 0:失败,1:成功
"JE": 0 // 0:失败,1:成功
}
}

Error:
"error": {
"code": "08012101"
}

error.code:
08012101:参数不足
0801000108010002: 设备不存在或云服务器不存在
08012102:私钥不正确
08012103:解密失败
08012104:超时过期
0801000308012105:操作失败
08012106:与设备通信失败

互联网切换设备数据上报主路径

  • API:
接口https://cloud.haiwell.com/api/project/machine/webApi/setBaseUrl
方法POST
作用设置设备中的 WEBAPI 上报服务器的主路径
  • 参数:
字段必填描述备注
account账号手机号或邮箱
machineCode机器码 PN
privateKey云数据中心项目私钥
webapiKeyWebApi 私钥
url上报服务器主路径
返回值:
Success:
"result": {
"code": 1, // 1 成功,0 失败
"data": "http://www.baidu.com" // 原值返回
}

Error:
"error": {
"code": "08012201"
}

error.code:
08012201:参数不足
0801000108010002: 设备不存在或云服务器不存在
08012202:私钥不正确
08012204:超时过期
08012203:解密失败
0801000308012205:操作失败
08012206:与设备通信失败

互联网获取设备数据上报主路径

  • API:
接口https://cloud.haiwell.com/api/project/machine/webapi/getBaseUrl
方法POST
作用获取设备中的 WEBAPI 上报服务器的主路径
  • 参数:
字段必填描述备注
account账号手机号或邮箱
machineCode机器码 PN
privateKey云数据中心项目私钥
webapiKeyWebApi 私钥
返回值:
Success:
"result": {
"code": 1, // 1 表示切换成功,0 表示切换失败
"data": "https://www.abc.com"
}

Error:
"error": {
"code":08012201
}
error.code:
08012201:参数不足
0801000108010002: 设备不存在或云服务器不存在
08012202:私钥不正确
08012204:超时过期
08012203:解密失败
0801000308012205:操作失败
08012206:与设备通信失败

局域网读取设备数据

  • API:
接口http://192.168.xxx.xxx/api/datagroup/getTagsValue
方法POST
作用读取数据组的通道变量的值
  • 参数:
字段是否必填描述备注
para加密的参数参考数据加密算法
para 加密前数据结构:
{
"machineCode": "6102193407020190011", // 机器码
"groupTag": "AAA", // 数据组名
"tags": ["W0", "B0"], // 字符串数组
"time": "1626694574488", // 当前设备时间
"timeout": 10 // 超时时间 <可选,单位秒,0 表示不超时>
}
返回值:
Success:
"result": {
"code": 1,
"data": {
"V0": "33",
"V1JE": "66"
}
}

Error:
"error": {
"code":08012101
}

error.code:
08012101:参数不足
08012102:私钥不正确
08012103:解密失败
08012104:超时过期
08012105:操作失败

局域网写入设备数据

  • API:
接口http://192.168.xxx.xxx/api/datagroup/setTagsValue
方法POST
作用写入数据组的通道变量的值
  • 参数:
字段是否必填描述备注
para加密的参数参考数据加密算法
para 加密前数据结构:
{
"machineCode": "6102193407020190011", // 机器码
"groupTag": "AAA", // 数据组名
"tags": {
"W0": "12",
"B0": "1"
}, // 通道标识数据对
"time": "1626694574488", // 当前设备时间
"timeout": 10 // 超时时间 <可选,单位秒,0 表示不超时>
};
返回值:
Success:
"result": {
"code": 1, // 0:有失败,1:全部成功
"data": {
"SL": 1, // 0:失败,1:成功
"JE": 1
}
}

Error:
"error": {
"code":08012101
}

error.code:
08012101:参数不足
08012102:私钥不正确
08012103:解密失败
08012104:超时过期
08012105:操作失败

局域网切换上报服务器主路径

  • API:
接口http://192.168.xxx.xxx/api/webapi/setBaseUrl
方法POST
作用切换 WEBAPI 上报服务器主路径
  • 参数:
字段是否必填描述备注
para加密的参数参考数据加密算法
para 加密前数据结构:
data = {
machineCode: "6102193407020190011", // 机器码
url: "https://www.baidu.com", // 上报服务器主路径
time: "1626694574488", // 当前设备时间<通过/api/getTime 取得>
timeout: 5, // 超时时间 <可选,单位秒,0 表示不超时>
}
返回值:
Success:
"result": {
"code": 1, // 0:失败 1:成功
"data": 1
}

Error:
"error": {
"code":08012101
}

error.code:
08012101:参数不足
08012102:私钥不正确
08012103:解密失败
08012104:超时过期
08012105:操作失败

局域网获取上报服务器主路径

  • API:
接口http://192.168.xxx.xxx/api/webapi/getBaseUrl
方法POST
作用切换 WEBAPI 上报服务器主路径
  • 参数:
字段是否必填描述备注
para加密的参数参考数据加密算法
para 加密前数据结构:
data = {
machineCode: "6102193407020190011", // 机器码
time: "1626694574488", // 当前设备时间<通过/api/getTime 取得>
timeout: 5, // 超时时间 <可选,单位秒,0 表示不超时>
}

```json title="返回值:"
Success:
"result": {
"code": 1, // 0:失败 1:成功
"data": "https://www.abc.com"
}

Error:
"error": {
"code":08012101
}

error.code:
08012101:参数不足
08012102:私钥不正确
08012103:解密失败
08012104:超时过期
08012105:操作失败

局域网取得设备时间

  • API:
接口http://192.168.XXX.XXX/api/getTime
方法POST
  • 参数:无
返回值:
Success:
"result": {
"data": 1626745870086 // 返回距 1970 年 1 月 1 日之间的毫秒数
}

数据加密和解密算法

为了安全,所传递的参数都必须加密后进行发送,主动推送的数据可以选择也使用加密发送,加解密算法选择AES-128-CBC算法,加解密的密钥(KEY)即在工程中在“数据上报服务器”中定义的私钥,而加密向量(IV)及具体示例请联系技术支持获取。