数据转发开发文档

使用须知

用户需要拥有自己的服务器以及合法域名或公网IP 。

接入指南

第一步:开通数据转发服务

在手机端绿刻度微信公众号-【我的】-【实用工具】-【数据转发】开通数据转发服务。

第二步:搭建服务器数据接收环境

服务开通后，绿刻度会将设备汇报的数据以json格式转发到用户服务器，开发者可以在服务器接收到数据后进行二次开发。具体转发的参数如下（注：以下表格只列出了最常用的部分字段，如开发中有疑问请联系客服）：
       Method:post
       Headers:{
               Content-Type:application/json;charset=UTF-8
       }
       Body:{
               json字符串（字段见下文）
       }

字段名	变量名	类型	示例值	描述	必包含
时间戳	time	String	20170906121120	当前数据的时间戳	是
设备ID	deviceId	String	8ECF8FB88888	作为设备的唯一ID，区分设备	是
设备名称	deviceName	String	远程温度计	设备自定义名称	是
信号强度	RSSI	String	-50	单位 : dbm	是
电量	voltage	String	100.0	单位 : %	是
数据上报间隔	reportInterval	Integer	600	单位 : s	是
外接电源	chargeState	String	1	0 : 断开状态，1 : 接通状态	否
经度	longitude	Double	116.397128	经度	否
纬度	latitude	Double	39.916527	纬度	否
传感器ID	sensorId	String	28BBC30AC01701AB-1	同一个设备下传感器的唯一标识	是
传感器名称	sensorName	String	温度	传感器名称	是
传感器标识	sensorFlag	String	temperature	可以通过该字段区分不同的传感器	是
传感器测量值	sensorVal	Float	25.5		是
传感器测量值单位	sensorUnit	String	℃		是
传感器报警范围	sensorScope	String	15_25		是
加密密钥	encryptionKey	String	1c3c977076628ba92f06107cf4f74ed8	将设备ID（deviceId）、时间戳（time）以及公众号中开通数据转发获得的appkey通过字典排序，之后进行MD5加密。若获得的结果与encryptionKey相同，证明数据来源是绿刻度	是

注：上表中“必包含”为“是”的字段无论任何设备都会转发，其他字段与设备类型有关。（建议开发者在接口调试成功之后，先打印出服务器接收到的json数据，以实际打印结果为依据进行开发。也可以参考/home/forward/log.txt路径下的文本文件（测试Demo会将转发的json数据写入/home/forward/log.txt文件中）。）

以远程温湿度计为例，其转发参数如下：

[{
      "time": "20170906121120",
      "deviceId": "8ECF8FB8",
      "deviceName": "远程温度计",
      "RSSI": -50,
      "voltage": 80,
      "reportInterval": 600,
      "encryptionKey": "1c3c977076628ba92f06107cf4f74ed8",
      "sensors": [{
            "sensorId": "28BBC30AC01701AB-1",
            "temperature": 22.5,(此字段是为了兼容旧版本，新开发的用户可忽略)
            "sensorName": "温度",
            "sensorFlag": "temperature",
            "sensorVal": 22.5,
            "sensorUnit": "℃",
            "sensorScope": "15_25"
         },
         {
            "sensorId": "28BBC30AC01701AB-2",
            "humidity": 31.7,
            "sensorName": "湿度",
            "sensorFlag": "humidity",
            "sensorVal": 31.7,
            "sensorUnit": "%",
            "sensorScope": "30_40"
         }]
}]

注：如果设备离线，监测数据会缓存到设备中，当设备上线时会将缓存的多组数据一起转发，其转发参数如下：

[{
      "time": "20170906121120",
      "deviceId": "8ECF8FB8",
      "deviceName": "远程温度计",
      "RSSI": -50,
      "voltage": 80,
      "reportInterval": 600,
      "encryptionKey": "1c3c977076628ba92f06107cf4f74ed8",
      "sensors": [{
            "sensorId": "28BBC30AC01701AB-1",
            "temperature": 22.5,(此字段是为了兼容旧版本，新开发的用户可忽略)
            "sensorName": "温度",
            "sensorFlag": "temperature",
            "sensorVal": 22.5,
            "sensorUnit": "℃",
            "sensorScope": "15_25"
         },
         {
            "sensorId": "28BBC30AC01701AB-2",
            "humidity": 31.7,
            "sensorName": "湿度",
            "sensorFlag": "humidity",
            "sensorVal": 31.7,
            "sensorUnit": "%",
            "sensorScope": "30_40"
         }]
},
{
      "time": "20170906120120",
      "deviceId": "8ECF8FB8",
      "RSSI": -52,
      "voltage": 70,
      "reportInterval": 600,
      "encryptionKey": "1c3c977076628ba92f06107cf4f74ed8",
      "sensors": [{
            "sensorId": "28BBC30AC01701AB-1",
            "temperature": 23.5,(此字段是为了兼容旧版本，新开发的用户可忽略)
            "sensorName": "温度",
            "sensorFlag": "temperature",
            "sensorVal": 23.5,
            "sensorUnit": "℃",
            "sensorScope": "15_25"
         },
         {
            "sensorId": "28BBC30AC01701AB-2",
            "humidity": 37.7,
            "sensorName": "湿度",
            "sensorFlag": "humidity",
            "sensorVal": 37.7,
            "sensorUnit": "%",
            "sensorScope": "30_40"
         }]
} ]

回传结果（用户服务器接收到转发的数据后，请返回以下字段给绿刻度）

字段名	必填	类型	示例值	描述
状态码	是	String	SUCCESS/ERROR	该字段作为绿刻度统计是否转发成功的依据

举例如下：

HttpServletResponse.getWriter().write("SUCCESS");// 接收成功回传SUCCESS
HttpServletResponse.getWriter().write("ERROR");// 接收失败回传ERROR

第三步:配置服务器数据接收地址

  用户服务器接收数据环境搭建完成之后，请到绿刻度微信公众号-【我的】-【实用工具】-【数据转发】配置服务器接收地址，测试成功后就可以正常接收绿刻度转发的数据，否则将无法正常使用。
  接收地址示例：
    域名方式 :http://www.lvkedu.com/data-forward/receiveData
    域名+端口方式 :http://www.lvkedu.com:8080/data-forward/receiveData
    IP地址+端口方式 :http://x.x.x.x:8080/data-forward/receiveData

Demo下载

数据转发开发Demo下载

注：测试Demo会将转发的json数据写入/home/forward/log.txt文件中，方便开发者开发。