一、统一说明

1、通讯方式
数据接口采用http协议，通讯内容采用JSON数据格式。
接口返回数据格式如下：
{"code":1001, "message":"信息内容", "data":object}
 
ResultData字段说明

字段	类型	说明
code	Integer	代码(参考返回代码说明表)
message	String	返回操作结果描述
data	Json	Json数据，具体格式参考各个接口

 
文档中所有接口的返回数据说明表，如无特殊说明均为ResultData数据格式，返回的数据均存放于data字段中

1. 接口调用注意事项

调用接口（除测试、登录接口外）需要将userId写入http请求头中。请求头字段名固定为userId，字段值为登录接口获取到的userId值。
userId通过登录接口获取。根据用户名和密码调用登录接口，登录成功后接口返回userId。
接口中如无特殊说明，采用post方法的接口中参数为json格式，放入请求body中；采用get方法的接口中参数为查询参数，放入请求地址后

1. 接口地址

通用云平台   http://www.xmsiyb.cn/
物联云平台  http://iot.xmsiyb.cn/
-k                      http://ip:port（默认9001）

二、接口详细

1、登录操作

1.1 地址可用性测试

1.1.1接口描述

 

接口编号	1.1
接口名称	接口可用性测试
功能描述	测试接口是否可用
接口地址	/app/TestConnect
请求方式	GET
参数格式	JSON
返回数据格式	String
备注

表1.1.1.1

1.1.2请求参数说明

字段	类型	说明
id	string	随机字符串

表1.1.2.1
 

1.1.3返回数据说明

测试通过返回请求的随机字符串
调用异常则表示为测试失败

1.1.4返回格式示例

{"code":1000,"message":"测试成功","data":"123"}
 

1.2 登录

1.2.1接口描述

 

接口编号	1.2
接口名称	登录接口
功能描述	用户登录
接口地址	/app/Login
请求方式	POST
参数格式	JSON
返回数据格式	JSON
备注

表1.2.1.1

1.2.2请求参数说明

字段	类型	说明
loginName	String	登录名
password	String	密码

表1.2.2.1
 

1.2.3返回数据说明

字段	类型	说明
userId	String	用户编号
userName	String	用户名
projectName	String	项目名称
authList	JSON数组	该用户所具有的权限列表，参考表1.2.3.3

表1.2.3.2
 
表.用户权限

权限	说明	备注
DeviceNew	新建设备
DeviceScan	扫描设备
DeviceEdit	编辑设备
DeviceDelete	删除设备
SystemSetting	系统设置
DataSync	数据同步
AlarmSetting	报警设置
ExportConfig	导出配置
ImportConfig	导入配置
Org	组织权限
QueryHistoryData	查询历史数据
QueryAlarmData	查询报警数据
DataEdit	数据编辑	重要
UserManager	用户管理
DeviceCoefficientEdit	设备参数编辑

表1.2.3.3

1.2.4返回格式示例

{
"code":1000,
"message":"登录成功",
"data":
{
"userId":"6a25694572484ac1a4c211fe4872b7dc",
"userName":"master",
"authList":
["DeviceNew","DeviceScan","DeviceEdit","DeviceDelete","SystemSetting","DataSync","AlarmSetting","ExportConfig","ImportConfig","Org","QueryHistoryData","QueryAlarmData","UserManager"]
}
}
 

2、设备操作

2.1 获取用户设备分组列表

2.1.1接口描述

 

接口编号	2.1
接口名称	获取用户的设备分组列表
功能描述	获取用户设备分组信息
接口地址	/app/GetUserDeviceGroups
请求方式	GET
参数格式	JSON
返回数据格式	JSON数组
备注

表2.1.1.1

2.1.2请求参数说明

请求头

字段	类型	说明
userId	String	用户编号

表2.1.2.1
 

2.1.3返回数据说明

字段	类型	说明
groupId	String	组编号
groupName	String	组名

表2.1.3.1

2.1.4返回格式示例

{"code":1000,
"message":"获取成功",
"data":
[
{"groupId":"733e5346f3414d1e840bfb7d8b581022","groupName":"温湿度"},
{"groupId":"d1a84321cee54503b6ab7f44c5474005","groupName":"气象"},
{"groupId":"eb3fab3155e64d7d9c74ef4a1f57fbf3","groupName":"未命名"}
]
}
 

2.2 获取设备信息及实时数据接口

2.2.1接口描述

 

接口编号	2.2
接口名称	获取设备信息及实时数据接口
功能描述	根据用户编号、设备组编号获取设备实时数据
接口地址	/app/GetDeviceData
请求方式	GET
参数格式	JSON
返回数据格式	JSON数组
备注

表2.2.1.1

2.2.2请求参数说明

请求参数

字段	类型	说明
groupId	String	设备组编号（接口2.1所获取的组编号）。如果获取所有数据，则该参数可以填空字符串””

表2.2.2.1
请求头

字段	类型	说明
userId	String	用户编号

表2.2.2.2
 

2.2.3返回数据说明

字段	类型	说明
groupId	String	组编号
deviceKey	String	设备编号
deviceAddr	Integer	设备地址
nodeID	Integer	节点编号
nodeType	Integer	节点类型1:模拟量1启用;2:模拟量2启用;3:同时启用
deviceDisabled	Boolean	停用状态，true停用
deviceName	String	设备名称
lng	Float	经度
lat	Float	维度
deviceStatus	Integer	设备运行状态，0未运行，1离线，2在线
realTimeData	JSON	实时数据,当两个模拟量同时启用时分别为模拟量1和模拟量2的实时数据。格式参考表2.2.3.2

表2.2.3.1

字段	类型	说明
dataName	String	模拟量名称
dataValue	String	实时数据
isAlarm	Boolean	是否报警
alarmMsg	String	报警信息

表2.2.3.2

2.2.4返回格式示例

{
"code":1000,
"message":"获取成功",
"data":[
{"groupId":"97a355ad117b45ae8bd7bdc4ee1af85b",
"deviceKey":"e33bdc470f484993aeabf79851532e82",
"deviceAddr":40000342,"nodeID":1,nodeType:3,"deviceDisabled":false,
"deviceName":"网络设备40000342#1",
"lng":0.0,"lat":0.0,"deviceStatus":2,
"realTimeData":
[{"dataName":"温度(℃)","dataValue":"0","isAlarm":false,"alarmMsg":""},
{"dataName":"湿度(%RH)","dataValue":"0","isAlarm":false,"alarmMsg":""}
]
},
{"groupId":"97a355ad117b45ae8bd7bdc4ee1af85b",
"deviceKey":"768a72794d3c4eb9a1ca7e4a049b3cf1",
"deviceAddr":40000342,"nodeID":2,nodeType:1,"deviceDisabled":false,
"deviceName":"模拟量1使能模拟量2禁用",
"lng":0.0,"lat":0.0,"deviceStatus":2,
"realTimeData":
[{"dataName":"温度(℃)","dataValue":"0","isAlarm":false,"alarmMsg":""}]
},
{"groupId":"97a355ad117b45ae8bd7bdc4ee1af85b",
"deviceKey":"59e0b7a349af4d96adf1e2f91efe0382",
"deviceAddr":40000342,"nodeID":3,nodeType:2,"deviceDisabled":false,
"deviceName":"模拟量1禁用模拟量2使能",
"lng":0.0,"lat":0.0,"deviceStatus":2,
"realTimeData":
[{"dataName":"湿度(%RH)","dataValue":"0","isAlarm":false,"alarmMsg":""}]
},
{"groupId":"97a355ad117b45ae8bd7bdc4ee1af85b",
"deviceKey":"482570be4a43433587193167460c6be6",
"deviceAddr":40000342,"nodeID":4,nodeType:1,"deviceDisabled":false,
"deviceName":"浮点设备",
"lng":0.0,"lat":0.0,"deviceStatus":2,
"realTimeData":
[{"dataName":"温度(℃)","dataValue":"0","isAlarm":false,"alarmMsg":""}]
},
{"groupId":"97a355ad117b45ae8bd7bdc4ee1af85b",
"deviceKey":"f491eebe9169465cb847ec4396efcc75",
"deviceAddr":40000342,"nodeID":5,nodeType:1,"deviceDisabled":false,
"deviceName":"开关量设备",
"lng":0.0,"lat":0.0,"deviceStatus":2,
"realTimeData":
[{"dataName":"温度(℃)","dataValue":"断开","isAlarm":false,"alarmMsg":"断开"}]
},
{"groupId":"97a355ad117b45ae8bd7bdc4ee1af85b",
"deviceKey":"27e66ad63e494ad2a2669de21c759901",
"deviceAddr":40000342,"nodeID":6,nodeType:1,"deviceDisabled":false,
"deviceName":"遥调设备",
"lng":0.0,"lat":0.0,"deviceStatus":2,
"realTimeData":
[{"dataName":"温度(℃)","dataValue":"北风","isAlarm":true,"alarmMsg":"北风"}]
}
]}

2.5 获取设备继电器状态接口

2.5.1接口描述

 

接口编号	2.5
接口名称	获取设备的继电器状态
功能描述	根据设备编号获取设备当前的继电器状态
接口地址	/app/GetRelays
请求方式	GET
参数格式	JSON
返回数据格式	JSON数组
备注

表2.5.1.1

2.5.2请求参数说明

请求参数

字段	类型	说明
deviceKey	String	设备编号（设备编号,如果查询所有继电器,则填写空字符串””）

表2.5.2.1
请求头

字段	类型	说明
userId	String	用户编号

表2.5.2.2
 

2.5.3返回数据说明

字段	类型	说明
deviceKey	String	设备编号
deviceStatus	Integer	设备运行状态，0未运行，1离线，2在线
relayID	Integer	继电器编号（从0开始）
realyName	String	继电器名称
status	Integer	继电器状态0闭合 1断开

表2.5.3.1

2.5.4返回格式示例

{
"code":1000,
"message":"获取成功",
"data":[
{"deviceKey":"2232","deviceStatus":2,"relayID":0,"realyName":"湖北中医院继电器1",
"status":0},
{"deviceKey":"2232","deviceStatus":2,"relayID":1,"realyName":"湖北中医院继电器2",
"status":0},
{"deviceKey":"2232","deviceStatus":2,"relayID":2,"realyName":"湖北中医院继电器3",
"status":0},
{"deviceKey":"2232","deviceStatus":2,"relayID":3,"realyName":"湖北中医院继电器4",
"status":0},
{"deviceKey":"2232","deviceStatus":2,"relayID":4,"realyName":"湖北中医院继电器5",
"status":0},
{"deviceKey":"2232","deviceStatus":2,"relayID":5,"realyName":"湖北中医院继电器6",
"status":0},
{"deviceKey":"2232","deviceStatus":2,"relayID":6,"realyName":"湖北中医院继电器7",
"status":0},
{"deviceKey":"2232","deviceStatus":2,"relayID":7,"realyName":"湖北中医院继电器8",
"status":0}
]
}

2.6 操作设备继电器状态接口

2.6.1接口描述

 

接口编号	2.6
接口名称	操作设备继电器状态接口
功能描述	根据设备编号操作设备的继电器状态
接口地址	/app/SetRelays
请求方式	Post
参数格式	JSON
返回数据格式	String
备注

表2.6.1.1

2.6.2请求参数说明

请求参数

字段	类型	说明
deviceKey	String	设备编号
relayId	Integer	继电器编号
opt	Integer	操作 0闭合 1断开

表2.6.2.1
 
请求头

字段	类型	说明
userId	String	用户编号

表2.6.2.2
 

2.6.3返回数据说明

字符串，表示操作结果；异常信息参考message字段

2.6.4返回格式示例

{"code":1000,"message":"操作成功","data":"操作成功"}
 

3、数据操作

3.1 查询历史数据

3.1.1接口描述

 

接口编号	3.1
接口名称	查询历史数据
功能描述	根据设备编号、时间等条件查询历史数据
接口地址	/app/QueryHistoryList
请求方式	GET
参数格式	JSON
返回数据格式	JSON数组
备注

表3.1.1.1

3.1.2请求参数说明

请求参数

字段	类型	说明
deviceKey	String	设备编号
nodeId	Integer	节点编号（如果查询所有节点的数据，则nodeId填写-1）
beginTime	DateTime	开始时间(YYYY-MM-dd HH:mm:ss)
endTime	DateTime	结束时间(YYYY-MM-dd HH:mm:ss)
isAlarmData	Integer	报警数据标识。-1查询全部数据，0查询正常数据，1查询报警数据

表3.1.2.1
 
请求头

字段	类型	说明
userId	String	用户编号

表3.1.2.2
 

3.1.3返回数据说明

字段	类型	说明
ID	String	编号
DeviceKey	String	设备编号
DeviceID	Integer	设备地址
NodeID	Integer	节点编号
Tem	Double	模拟量1值 （文档中只是示例，以平台实际节点名称为准。不同的传感器表示的意义不同。例如温湿度传感器，该值表示为温度值；PM传感器表示为PM10的值。 具体参考传感器类型。）
Hum	Double	模拟量2值 （文档中只是示例，以平台实际节点名称为准。不同的传感器表示的意义不同。例如温湿度传感器，该值表示为湿度值；PM传感器表示为PM2.5的值。 具体参考传感器类型。）
Lng	Double	经度
Lat	Double	维度
CoordinateType	Integer	坐标类型 0百度坐标，1移动基站 2联通基站 3GPS
RecordTime	Datetime	记录时间
IsAlarmData	Integer	是否为报警数据，0正常数据，1报警数据
RecordTimeStamp	Long	记录时间时间戳
DeviceName	String	设备名称

表3.1.3.1

3.1.4返回格式示例

{
"code":1000,
"message":"获取成功",
"data":
[
{"ID":"139c213100b64ab581268b42acfa85b7","DeviceKey":"dfea0630a8e949d9b828647f4b8bfbfc","DeviceID":40001739,"NodeID":1,"Tem":0.0,"Hum":0.0,"Lng":0.0,"Lat":0.0,"CoordinateType":2,"RecordTime":"2018-04-07 15:28:35","IsAlarmData":0,"RecordTimeStamp":1523086115000,"DeviceName":"网络设备40001739#1"},
{"ID":"c0c90da1abe749e89510b62e2128600e","DeviceKey":"dfea0630a8e949d9b828647f4b8bfbfc","DeviceID":40001739,"NodeID":1,"Tem":0.0,"Hum":0.0,"Lng":0.0,"Lat":0.0,"CoordinateType":2,"RecordTime":"2018-04-07 15:23:35","IsAlarmData":0,"RecordTimeStamp":1523085815000,"DeviceName":"网络设备40001739#1"},
{"ID":"1aa66f2c293d431d92218cc7246f267d","DeviceKey":"dfea0630a8e949d9b828647f4b8bfbfc","DeviceID":40001739,"NodeID":1,"Tem":0.0,"Hum":0.0,"Lng":0.0,"Lat":0.0,"CoordinateType":2,"RecordTime":"2018-04-07 15:20:50","IsAlarmData":0,"RecordTimeStamp":1523085650000,"DeviceName":"网络设备40001739#1"}
]
}
 
 

三、附录

返回代码

 

代码	说明
1000	接口执行成功，具体参考各个接口
1001	接口执行失败，具体参考各个接口，原因参考Message
1002	参数错误
1003	程序内部异常，异常信息参考Message
1004	鉴权失败