泸州扬尘噪音监测设备数据接口标准 （版本1.0）

扬尘噪音监测设备数据接口标准

（版本1.0）

目录

1 前言PAGEREF _Toc81373

2 编码规则PAGEREF _Toc54693

2.1 协议规范与名称解析PAGEREF _Toc286683

3 接口调用PAGEREF _Toc70343

3.1 接口说明PAGEREF _Toc242263

3.2 服务器地址PAGEREF _Toc74763

3.3 接口方式PAGEREF _Toc323964

3.3.1 接口概述PAGEREF _Toc91644

3.3.2 API的地址与请求方法PAGEREF _Toc140524

3.3.3 API响应格式PAGEREF _Toc64034

3.3.4 API的校验机制与编码规则PAGEREF _Toc298574

3.3.5 注意事项PAGEREF _Toc80085

3.4 接口列表PAGEREF _Toc236785

3.4.1 注册设备/设备上线PAGEREF _Toc195315

3.4.2 设备下线PAGEREF _Toc106956

3.4.3 设备心跳维持PAGEREF _Toc248577

3.4.4 实时数据PAGEREF _Toc21747

3.4.5 时间校对PAGEREF _Toc133639

附录一API响应状态码PAGEREF _Toc2806011

1 前言

本标准描述了扬尘数据上报接口的规范，主要用于解决设备注册、上线、扬尘数据上报等问题。

2 编码规则

2.1 协议规范与名称解析

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

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

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

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

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

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

3 接口调用

3.1 接口说明

扬尘数据上报接口上报设备上线信息、设备下线信息、设备心跳维持信息、设备实时数据信息、时间校对信息，实现数据的更新和存储。

3.2 服务器地址

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

3.3 接口方式

3.3.1 接口概述

扬尘数据上报接口采用REST API的方式，传输数据格式为JSON。API允许有GET、POST、PUT、DELTE四中方法。其中GET、POST、PUT、DELETE为客户端调用API的方法。

3.3.2 API的地址与请求方法

API地址格式：http://api_root/{monitortype}/v1.0 /{servicename}

API地址包括三部分：服务器地址，监测设备类型，版本号，服务名称。如上述地址表示API服务器地址为http://api_root，监测设备类型为{monitortype}，版本号为：v1.0，服务名称为{servicename}。

扬尘监测设备类型({monitortype}） 为dustdetection。

API请求方法为POST。

3.3.3 API响应格式

API响应指调用API后返回客户端的信息。API响应数据为如下格式：

{

  "StatusCode":0,       --响应状态，具体状态码见附录一

"MonitorType":0,      --设备类型

"Result":{/*响应JSON格式数据域*/}

}

注：本文档中API调用返回中出现的“StatusCode”都指响应状态（见附录一）

3.3.4 API的校验机制与编码规则

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

用户设备的每次请求均需要在HTTP请求的header中加入厂商唯一的Api Key。

注：ApiKey与ApiUID需要联系平台方申请分配。

简易的C#示例代码如下:

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

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

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

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

编码规则：采用UTF8。

3.3.5 注意事项

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

本文档中的时间均使用yyyy-MM-dd HH:mm:ss格式（时区为UTC+8）。

本文档中的float为单精度浮点数。

本文档中“是否必填”列中的值“M”表示必填。

3.4 接口列表

3.4.1 注册设备/设备上线

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

请求参数：

返回结果：

请求示例：

{

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

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

"DeviceType":2,                --设备类型代码

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

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

}

返回示例：

{

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

"MonitorType":2,            --设备类型

"Result":{

"Id":1         --设备ID

}

}

注意事项：如果其他命令返回数据时提示“设备未上线或已经下线，请重新注册/上线”需重新发送此注册/上线命令。

3.4.2 设备下线

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

3.4.3 设备心跳维持

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

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

3.4.4 实时数据

设备正常工作时每隔60S生成并发送一条实时数据。

请求参数：

返回结果：

请求示例：

{

"Id":1,         --设备ID（注册上线后返回的ID，后续章节相同含义）

"Index":index,           --表示当前发送数据的序号

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

" TSP ":100.0,               -- TSP粉尘浓度

" PMTen ":56,             -- PM10（μg/m3）

" PMTwoPointFive ":45,        -- PM2.5（μg/m3）

" Noise ":30,               --环境噪声(db)

" Temperature ":25,           --空气温度(t)

" Humidity ":95.0,            --空气湿度(%)

"WindSpeed":1.25,         --风速(m/s)

" Atmospheric ":125.0,          --气压 单位kpa(千帕)

" WindDirection ":125.0,       --风向(°)

" AirQuality ":2,          --空气质量

" Warn ":0,            --系统预警状态编码

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

}

返回示例：

{

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

"MonitorType":0,              --设备类型0表示塔吊

1表示施工升降机

2表示扬尘噪音

"Result":{

" Index ":1              --运行数据序号

}

}

3.4.5 时间校对

请求参数：

返回结果：

返回示例：

{

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

"Result":{

" ServerTime ":”2012-12-18 01:10:22”           --运行数据序号

}

}

注意事项：终端设备发送时间校对申请，API服务器收到请求，并返回服务器时间。

附录一API响应状态码