接口规范

1. 交互topic定义

指令下发：

/v1/devices/{DeviceSn}/{Module}/{Operation}

指令响应：

/v1/devices/{Module}/response

交互说明：

当端侧收到指令时：会立即返回一个response消息，执行完成之后会再进行一次结果的上报

Module支持的模块有：`device、network、virtualization、app、security、system`

Operation支持的操作有：`set、get、command`

事件上报：

/v1/devices/{Module}/events

对于终端监测到的一些事件，通过该topic进行上报

数据上报：

/v1/devices/{Module}/datas

基本的量测数据会通过这个topic进行上报

---

2. 报文格式

2.1. 指令下发报文

物联管理平台对终端发送指令时采用轻量级的JSON格式，通用报文字段如下表所示

公共请求参数

数据域	数据类型	是否必选	描述
mid	stirng	是	消息ID，推荐使用uuid, 请求和应答匹配，用来匹配请求和应答消息和去重
msgTime	string	是	消息发送时间戳，RFC3339标准，例如：1985-04-12T23:20:50.52Z
zone	string	否	设备部署的区域，例如ZONE3
node	string	否	设备部署的节点，例如440000
requestId	string	否	微服务链路追踪用的标识
deviceSn	string	是	设备ESN码
deviceId	string	否	统一物联网平台分配的设备id，可能会重复，不能唯一标识设备
service	string	是	服务名称。对应具体的完成指令的功能模块
cmd	string	是	具体操作方法
params	object	否	[可选]对象内容

后续所有的指令报文定义时，只用于明确params的结构

请求示例

{
    "mid": 54132,
    "service": "service1",
    "cmd": "command1",
    "params": {
        "key": "value"
    },
    "zone":"设备部署的区域",
    "node":"设备部署的节点",
    "deviceSn": "D23pigXo",
    "deviceId": "A1234456",
    "requestId":"xxxxxxxxxx",
    "msgTime": "1985-04-12T23:20:50.52Z"
}

---

2.2. 响应报文

当终端收到物联管理平台发送的指令时，需要立即返回一个响应报文，响应报文的格式如下：

数据域	数据类型	是否必选	描述
mid	string	是	消息ID，用于消息去重。
replyId	string	是	表示响应的是哪条请求指令，为该指令的mid，用来匹配请求和应答
msgTime	string	是	消息发送时间戳，采用RFC3339标准，例如：1985-04-12T23:20:50.52Z。
zone	string	否	设备部署的区域，例如ZONE3
node	string	否	设备部署的节点，例如440000
requestId	string	否	微服务链路追踪用的标识
deviceSn	string	是	设备ESN码
deviceId	string	否	统一物联网平台分配的设备id，据说可能会重复，不能唯一标识设备
code	uint16	是	标识应答的返回码： 批处理请求时，如果所有处理都成功，返回200 如果有部分失败，返回400 取值如下： •100：指令接收成功，等待执行完成。•200：请求成功。 •400：请求消息错误，例如消息格式错误等。 •404：不支持该操作。 •429：请求太多。 •500：服务端内部错误，由应用定义。
body	object	否	（可选）对象内容。

响应示例

 {
    "mid": "54132",
    "replyId": "54132",
    "code": 200,
    "body": {
        "key": "value"
    },
    "zone":"设备部署的区域",
    "node":"设备部署的节点",
    "deviceSn": "D23pigXo",
    "deviceId": "A1234456",
    "requestId":"xxxxxxxxxx",
    "msgTime": "1985-04-12T23:20:50.52Z "
}

---

2.3. 事件报文

参数说明

字段名	必选/可选	类型	参数描述
devices	必选	DeviceS[]	设备数据

DeviceS结构体说明

字段名	必选/可选	类型	参数描述
deviceSn	必选	String(256)	设备ESN码
services	必选	List<Service>	服务列表。

Service结构体说明

字段名	必选/可选	类型	参数描述
service	必选	String(256)	服务名。
mid	必选	string	消息ID，用来匹配请求消息和应答消息，以及消息去重。
data	必选	jsonObject	服务数据。
eventTime	必选	string	告警发生的时间，采用RFC3339标准，例如：1985-04-12T23:20:50.52Z。

data结构体说明

仅供参考，这块不是固定的，会根据具体的事件情况做调整

字段名	必选/可选	类型	参数描述
eventType	必选	string	告警类型。
qualifier	可选	string	（可选）告警子类型。如：cpuUsed、cpuTemp、memUsed等
indication	必选	uint16	告警指示，取值如下： •0：消除告警 •1：产生告警 •2：刷新告警
severity	必选	string	告警级别，取值如下：Critical紧急 Major重要 Minor次要 Warning提示
params	可选	object	（可选）告警附加信息。

事件报文示例

{
    "devices": [
        {
            "deviceSn": "D3183Tth3w",
            "services": [
                {
                    "service": "serviceName",
                    "mid":"mymessageId",
                    "data": {
                        "eventType": "CpuUtilizationRising",
                        "qualifier": "",
                        "indication": 0,
                        "severity": "Warning",
                        "params": {
                            "cpuUsage":"18.49%",
                            "cpuUsageThreshold":"80%"
                        }
                    } 
                    "eventTime": "2020-07-27T13:40:16.00Z" 
                }
            ]
        }
    ]
}

---

2.4. 数据报文

参数说明

字段名	必选/可选	类型	参数描述
devices	必选	DeviceS[]	设备数据。

DeviceS结构体说明

字段名	必选/可选	类型	参数描述
deviceSn	必选	String(256)	设备ESN码
services	必选	List<Service>	服务列表。

Service结构体说明

字段名	必选/可选	类型	参数描述
service	必选	String(256)	服务名。
mid	必选	string	消息ID，用来匹配请求消息和应答消息，以及消息去重。
data	必选	jsonObject	服务数据。
dataTime	必选	String(256)	时间格式：RFC3339标准，例如：1985-04-12T23:20:50.52Z。

数据报文示例

{
    "devices": [
        {
            "deviceSn": "D68NZxB4",
            "services": [
                {
                    "mid":"mymessageid",
                    "service": "serviceName",
                    "data": {
                        "key": "value"
                     },
                     "dataTime": "2019-10-23T17:36:25Z" 
                 }
             ]
        }
    ]
}

---

3. 公共说明

所有字段，如果属于可选，且没有值的时候，一律直接不传该字段，而不是传空值。