前端开发说明¶

前台终端包括PC桌面端、安卓/IOS的APP、大屏等，支持各种语言及开发工具，前端与后端通讯主要包括两种方式，一种为直接访问实时数据：通过MQTT协议，可以通过Web Socket技术直接获取某个设备类型(频道) 的设备实时数据并进行实时控制，另一种是经过后台业务逻辑模块处理的业务数据：通过HTTPS协议，RESTful API的方式提供访问，数据格式采用JSON。本文档包含了所有数据的频道名、数据格式等，具体API参数、调用样例等说明请查阅 API 文档。

连接地址与端口¶

版本环境	地址	端口
生产版	dev.iotqsgf.com	https(8443)
测试版
开发版

版本与发布机制¶

系统开发与发布采用3个版本迭代开发的方式，同时存在三个版本：生产版、测试版、开发版。举例说明：系统在第一次迭代的过程如下：首先产生开发版–1.0.0，开发版随时可能重启，因为程序是以最激进的方式在变化，当开发版做出一定功能时，将迭代到测试版上线：1.0.0，此时开发版为：1.0.0。测试版用于测试，代码稳定不更新，待通过一定测试后，将迭代到生产环境上线：1.0.0，此时测试版为：1.0.0，开发版为：1.0.2。后续以此类推。前端开发过程中可以根据需要连接目标环境。

注：系统尚未上线，开发测试均使用生产版环境

实时通讯¶

实时数据访问端口:

11885(Socket,未加密,稍后将关闭)

118886(Socket,加密访问)

wss://tbh.iotqsgf.com/wss:443 (Web Socket,加密访问)

实时通讯即通过云平台的代理服务，直接获取某个站和设备的实时数据，也可以下达实时命令，为保证通讯时效性，该数据未经云平台端处理，直接与在地端设备进行点对点实时通讯。

实时通讯采用可能成为物联网标准协议的MQTT协议。MQTT协议是一个面向物联网应用的即时通信协议，使用TCP/IP提供网络连接，能够对负载内容实现消息屏蔽传输，开销小，可以有效降低网络流量。

实时通讯基于Topic的订阅、发布以及消息推送，可以实现设备间的消息单播以及组播。

主题（Topic）格式定义¶

字段	说明	举例
tdqs	Topic （主题）	tdqs
能源站ID	五位字符串	00001
版本	点分十进制（3段）	1.0.0
频道类型	rd：实时数据 cmd：命令 update：升级	rd
设备类型	设备类型ID	1

格式例子:

tdqs/00001/1.0.0/rd/1

表示：订阅或发布 站ID=00001 （能源站即智能网关)的电表（类型ID为1）的实时数据

具体数据在消息字段内容中（JSON）

tdqs/00001/1.0.0/cmd/1

表示：订阅或发布 站ID=00001 的电表的实时命令

具体数据在消息字段内容中 （JSON）

实时数据消息内容（JSON）格式定义¶

格式:

{
  "time":"时标","data":[
   {
        "设备ID" : 设备1的ID值,
        "数据信息码1" : 数据值,
        "数据信息码2" : 数据值,
        "数据信息码n" : 数据值
   },
   {
        "设备ID" : 设备2的ID值,
        "数据信息码1" : 数据值,
        "数据信息码2" : 数据值,
        "数据信息码n" : 数据值
   },
   {
        "设备ID" : 设备n的ID值,
        "数据信息码1" : 数据值,
        "数据信息码2" : 数据值,
        "数据信息码n" : 数据值
   }
 ]
}

例子:

    {
    "time":"2017-12-22 8:30:00","data": [
      {
        "ID" : 1,
        "1001" : 10.3,
        "1006" : 12.1,
        "1007" : 16.2
      },
      {
        "ID" : 2,
        "1001" : 11.1,
        "1006" : 14.2,
        "1007" : 19.2
      },
      {
        "ID" : 3,
        "1001" : 19.2,
        "1006" : 12.3,
        "1007" : 16.1
      }
  ]
}

本例子表示发布或订阅到设备ID=1，2，3三个电表设备的有功电能值、有功功率、无功功率三个值。

说明：

字段	说明	举例
时标	YYYY-MM-DD HH:MM:SS	2017-12-22 8:30:00
设备ID	数值类型为整数	“ID” : 1
数据信息码	数值类型为浮点数	“1001” : 19.2

命令类型通讯格式定义(JSON)¶

格式:

 {
     "time" : "时标",
     "userid" : "用户ID ",
     "data" : [
                 {
                   "设备ID" : 设备1的ID值,
                   "数据信息码1" : 数据值,
                   "数据信息码2" : 数据值,
                   "数据信息码n" : 数据值
                     },
                    {
                   "设备ID" : 设备2的ID值,
                   "数据信息码1" : 数据值,
                   "数据信息码2" : 数据值,
                   "数据信息码n" : 数据值
                },
                    {
                   "设备ID" : 设备n的ID值,
                   "数据信息码1" : 数据值,
                   "数据信息码2" : 数据值,
                   "数据信息码n" : 数据值
                     }
             ]
}

API格式与样例¶

API是经过能源平台后台服务模块采集数据后，通过各种算法模块进行大数据逻辑分析以后提供的服务功能函数，采用RESTful API方式提供服务。

为保证安全性，任何一次服务功能的调用必须提供安全认证Token，该Token是一个采用随机加密算法处理的字符串，用户在通过身份认证后会获得该Token，以后每次功能调用必须提供，用户注销或重新登陆该Token失效，验证算法保存在服务器端，可以保证安全性。

基本格式：

地址/版本号/API函数名

例子:

https://www.iotqsgf.com/1.0.0/confirmcode

GET方式例子:

curl -X GET
          -H "Session-Token: XXXXXXX"
          -H "Project-ID: XXXXX"
          https://www.iotqsgf.com/1.0.0/queryapi\?tablename\=ts_user

POST方式例子:

curl -X POST
          -H "Session-Token: XXXXXXX"
          -H "Project-ID: XXXXX"
          -d '{"userid":"xxxxx","data":{"f1":"xx","f2":"xx"}}'
          https://www.ioqsgf.com/1.0.0/update_user_info