泸州市智慧工地综合管理信息平台 施工升降机监控系统数据接口标准 （版本1.0）

泸州市智慧工地综合管理信息平台

施工升降机监控系统数据接口标准

（版本1.0）

泸州市住房和城乡建设局

2020年9月

目录

1 前言 25

2 编码规则 25

2.1 协议规范与名称解析 25

3 接口调用 25

3.1 接口说明 25

3.2 服务器地址 25

3.3 接口方式 26

3.3.1 接口概述 26

3.3.2 API基地址 26

3.3.3 GET方法 26

3.3.4 POST方法 26

3.3.5 API的校验机制和编码规则 26

3.3.6 注意事项 27

3.4 接口列表 27

3.4.1 注册设备/设备上线 27

3.4.2 设备下线 28

3.4.3 设备心跳维持 29

3.4.4 实时数据上报 29

3.4.5 时间校对 32

3.4.6 报警上传 33

3.4.7 工作数据上报 34

3.4.8 限位参数 37

1 前言

本标准主要用于解决以下问题：

l 解决设备注册、设备上线、上报数据DeviceType重复的问题。

l 完善APIKey（新增一些必要的数据）。

l 优化数据上报地址。

l 优化注释，便于上报者理解。

2 编码规则

2.1 协议规范与名称解析

(1) API地址（REST服务地址）全部小写。

(2) JSON数据内容是用Pascal命名规则。

(3) 协议中出现的时间隔，比如每隔60s发送一次运行数据等，根据具体设备而定（即由设备厂商确定）。

(4) JSON: 一种轻量级的数据交换格式。

(5) REST API: 符合rest风格的应用程序接口。

(6) 心跳：设备为保持通讯链路，定时发送少量数据。

(7) API网关集群（API云）。

(8) 通信网关集群：

(9) 文档规范：一级标题使用三号黑体字，二级标题使用4号宋体字，正文使用小四字体。代码以及备注使用5号宋字体。

3 接口调用

3.1 接口说明

升降机数据上报接口上报设备上线信息、设备下线信息、设备心跳维持信息、设备实时数据信息、时间校对信息，报警上传信息、工作数据信息、限位参数信息实现数据的更新和存储。

3.2 服务器地址

服务器地址（API地址中api_root部分）： http://api.safe110.net:9991

3.3 接口方式

3.3.1 接口概述

数据采集接口分为：设备主动上报REST API、设备参数获取设置API。

REST API使用HTTP拉取实现。传输数据格式约定为JSON。API允许有GET、POST、PUT、DELTE四中方法。其中GET、POST、PUT、DELETE为客户端调用API的方法。

3.3.2 API基地址

命令地址格式：http://apiurl /v1.0 /{servicename}

API基地址包括三部分：域名，版本号，API服类型，服务名称。如上地址表示API服务器域名为：http://apiurl，版本号为：v1.0，服务名称：servicename。

注：花括号内为可变内容，不作为uri中的字符。

3.3.3 GET方法

命令地址格式2：http:// apiurl /v1.0/ {serveicename}?id={id}&arg={arg}

id：指注册上线后返回的设备ID

arg：携带的参数[可选]

3.3.4 POST方法

命令地址格式：http:// apiurl /v1.0 /{serveicename}

3.3.5 API的校验机制和编码规则

API服务器在每次收到数据后会根据Http包头携带的ApiKey校验数据的有效性。并判断数据来源的设备厂商等相关信息。

用户设备的每次请求，均需要在HTTP请求的header中加入厂商唯一的API Key。简易的C#示例代码如下：

request.Headers.Add("ApiKeyValue: kL3HGhesgOY=");

request.Headers.Add("ApiUID: 3DEADFC6-9D60-4358-B845-9A6D646B303F");

request.Headers.Add("ApiKeyType: 0");

request.Headers.Add("DeviceSN: 010713030031 ");

编码规则：采用UTF8

3.3.6 注意事项

l 本文档JSON数组定义格式为[{“Data”:”XX”},{/*第2-N个值*/}]，JSON数组可以为空,而不是指必须有一个元素。

l 本文档中代码部分时间均使用yyyy-MM-dd HH:mm:ss格式。

l 本文档中出现的“XXX设置的响应状态上报”均指网站参数设置的响应部分，参数设置请求由网站模拟Socket通信，这里不需要处理。

l 所有参数（包括设备主动与服务端主动）均通过API POST方法上报，其中服务端主动的参数获取，在本文档中都以API POST方法上报实现网站Socket获取的响应。

3.4 接口列表

3.4.1 注册设备/设备上线

对此URL进行Post请求将为您注册一个新设备：

请求参数：

返回结果：

请求示例：

{

"SN":"B1080106",          --设备序列号  

"Type":"B",                 --设备类型简称

"ParamCanSet":0,           --设备是否可以设置参数

"DeviceType":"0"     --设备类型代码

"DeviceIp":"127.0.0.1:8888"     --设备IP与端口信息

"ParamsAppIP":”127.0.0.1:8001”  -string 参数设置应用程序IP与端口信息

}

返回示例：

{

"StatusCode":0,              --响应状态

"Result":{

"Id":1,           --设备ID Int32

}

}

3.4.2 设备下线

终端设备主动将设备置为下线状态。

3.4.3 设备心跳维持

终端设备每隔一定时间（默认60S）发送一次心跳请求，保证设备在线。如果API服务端在三次心跳间隔时间内没有收到设备端发送的心跳包，那么认为设备已经下线。

附注：这里的ID指设备注册上线后返回的设备ID。 本文档后续章节中如无特别声明，出现的ID都指设备ID，在服务器注册时分配。

3.4.4 实时数据

设备上线时主动上报实时数据。

请求参数：

返回结果：

请求示例：

{

-- 批量数据列表

"Id":1,               --设备ID

"Index ":1,              --序号  表示当前发送数据列表中的最大序号

"CollectionTime":"2014-01-01 12:12", --采集时间 格式2012-10-27 01:12:24

"LoadValue":2.50,                --Float 吊重(t)

"PercentRate":2.50,               --Float 载重百分比

"NumberOfPeople":5,             --Int32 人数

"GPRSOnline":1,                --Int32  GPRS模块在线状态

"RecognizeState":2.50,            --Int32 识别方式

"IDNO":"123456789",              --String 司机ID

"LockState":1,             --Int32 锁机状态

"DisplayRequestCode":1,          --Int32 显示器操作请求码

"Wind":125.0,                  --Float 风速，单位：米/秒

"Height":20.12         --Float 设备运行高度

"Speed":2,                       --Float 设备运行速度

"Angle":0,              --Float 倾斜角度

"CallFloor":1,         --Int32  呼叫楼层

"RelFloor":1,         -- Int32  当前楼层

"LimitSwitch":1,        --Int32  限位开关状态 1：打开  0：关闭  

bit0：上限位；bit1：下限位；

bit2：内门限位；bit3：外门限位

"Handle":1,                --Int32 手柄状态

"RunningState":1,             --Int32 升降机运行状态  0：停止；1：上升；2：下降

"Bypass":1,                    --Int32 升降机运行状态  0：停止；1：上升；2：下降

"EarlyAlarm":1,                --Int32 预警状态

"Alarm":1,                            --Int32 报警状态 

}

返回示例：

{

"StatusCode":0             --响应状态 

"Result":{

"MaxIndex":12      --长整形表示当前发送历史数据列表中的最大序号

}

}

3.4.5 时间校对

请求参数：

返回结果：

返回示例：

{

"StatusCode":0,                --响应状态，状态值见附录一

"Result":{

" ServerTime ":"2013-12-12 12:12:12",         --运行数据序号

}

}

注意事项：终端设备发送时间校对申请，API服务器收到请求，并返回服务器时间。时间格式：yyyy-MM-dd HH:mm:ss；

3.4.6 报警上传

报警从有到无时上报一次报警信息

请求参数：

返回结果：

请求示例：

{

"Id":1,                -- Int32 设备ID  

"StartTime":”2012-10-27 01:12:24”, --报警开始时间 格式2012-10-27 01:12:24

"EndTime":”2012-10-27 01:12:24”,  --报警结束时间 格式2012-10-27 01:12:24  

"PreAlarm":1,       -- Int32 系统预警状态编码

"Alarm":125,       -- Int32 系统报警状态编码

"LoadAlarm":true,      -- Bool 吊重报警 false未报警，true报警

"NumberAlarm": true,     -- Bool 人数报警 false未报警，true报警

}

返回示例：

{

"StatusCode":0,           --响应状态，状态值见附录一

"Result":{/*扩展数据，暂时为空*/}

}

3.4.7 工作数据上报

上报升降机工作数据

请求参数：

返回结果：

请求示例：

{

-- 批量数据列表

"Id":1,                 --设备ID

" Index ":1,               --流水号  表示当前发送数据列表中的最大序号

"CollectionTime":"2014-01-01 12:12",  

"RunStarTime":"2013-12-12 12:12:12",    --时间格式 升降机启动时间

"RunEndTime":"2013-12-12 12:12:12",       --时间格式 升降机结束时间

"LoadValue":12.10,                --Float 本次工作循环中最大载重量（t）

"PercentRate":12.10,                --Float 本次工作循环中最大百分比(%)

"NumberOfPeople":1,                 --Int32 人数

"StartFloor":1,                --Float 开始楼层

"EndFloor":2,              --Float 结束楼层

"Wind":2.23,               --Float 最大风速(m/s)

"Speed":2.23,               --Float 本次循环作业中平均速度

"Angle":2.23,              --Float  本次循环作业中最大倾角

"IDNO":"123456789",            --String 司机ID（18）

"RunningState":1,         --Int32 运行状态 1：上升 2下降

"Bypass":1,          --Int32  Bypass状态

"EarlyAlarm":1,         -- Int32 系统预警状态编码

"Alarm":1,           -- Int32 系统报警状态编码

}

返回示例：

{

"StatusCode":0,               --响应状态，状态值见附录一

"Result":{

"MaxIndex ":12,           --长整形 最大的序号

}

}

注意事项：升降机运行至停止生成一条工作数据，为防止波动生成数据，每一次过程至少要经过5s，少于5s不予记录。

3.4.8 限位参数

上报升降机限位参数记录

请求参数：

返回结果：

请求示例：

{

"PackIndex":1,                   --包索引

"DataList":[{    

"Id":1,                 --设备ID

"CollectionTime":"2012-12-12 12:12:12",   --采集时间 格式2012-10-27 01:12:24

"RatedLoad":4000,          --Float 额定载重（kg）

"EarlyAlarmPercent":90,         --Float 预警百分比（%）

"AlarmPercent":100,                 --Float  报警百分比（%）

"RatedPeople":9,          --Int32 额定人数

"WindEarlyAlarm":3.0,         --Float 风速预警

"WindAlarm":4.0,          --Float 风速报警

"SpeedEarlyAlarm":3.0,         --Float 运行速度预警

"SpeedAlarm":4.0,          --Float 运行速度报警

"Height":9.0,           --Float 升降机高度

"HeightEarlyAlarm":3.0 ,         --Float 高度预警

"HeightAlarm":4.0,          --Float 高度报警

"AngleEarlyAlarm":3.0,         --Float 倾斜角度预警

"AngleAlarm":4.0,          --Float 倾斜角度报警

},  {/*第2~N条历史记录*/}]

]

}

返回示例：

{

"StatusCode":0,                --响应状态，状态值见附录一

"Result":{

"MaxIndex":12,        --长整形 当前发送批量数据的最大序号

}

}

附录一 API响应状态码