10 KiB
简介
用户创建完产品后即可定义数据模板，基于导出数据模板json配置文件通过SDK提供的脚本工具可以自动生成数据模板配置代码，设备调试阶段的在线调试会接收设备的上报数据并可在控制台下发控制指令到设备进行调试。本文档介绍数据模板协议。
数据模板协议
概述
物联网开发平台定义了一套通用的方法，实现设备的统一描述、统一控制，进而提供数据的流转和计算服务，实现不同设备的互联互通、数据的流转和融合，助力应用落地。
产品定义了数据模板以后，设备可以按照数据模板中的定义上报属性、事件，并可对设备下发远程控制指令，即对可写的设备属性进行修改。数据模板的管理详见 产品定义。数据模板协议包括了以下几部分。
- 设备属性上报：设备端将定义的属性根据设备端的业务逻辑向云端上报。
- 设备远程控制：从云端向设备端下发控制指令，即设置设备可写属性。
- 获取设备最新上报信息：获取设备最新的上报数据。
- 设备事件上报：设备可根据定义的数据模板中的事件，当事件被触发，则根据设备事件上报的协议上报告警、故障等事件信息。
- 设备行为：云端可以通过 RPC 的方式来要求设备执行某个动作行为，适用于应用需要实时获取设备的执行结果的场景。
设备属性上报
1.当设备需要向云端上报数据时，开发平台为设备设定了默认的 Topic
- 上行请求 Topic：
$thing/up/property/{ProductID}/{DeviceName} - 上行响应 Topic：
$thing/down/property/{ProductID}/{DeviceName}
2.请求
-
设备端请求报文示例：
{ "method":"report", "clientToken":"123", "timestamp":1212121221, "params":{ "power_switch":1, "color":1, "brightness":32 } } -
参数说明：
参数 类型 说明 method String report表示设备属性上报clientToken String 用于上下行消息配对标识 timestamp Integer 属性上报的时间，SDK默认省略 params JSON JSON 结构内为设备上报的属性值 -
sdk接口：
IOT_DataTemplate_PropertyReport
3.响应
-
云端返回设备端报文示例：
{ "method":"report_reply", "clientToken":"123", "code":0, "status":"some message where error" } -
响应参数说明：
参数 类型 说明 method String report_reply表示云端接收设备上报后的响应报文clientToken String 用于上下行消息配对标识 code Integer 0表示云端成功收到设备上报的属性status String 当code非0的时候, 提示错误信息 -
sdk回调：
PropertyMessageCallback.method_control_callback
设备远程控制
1.云端下发控制指令使用的 Topic：
- 下发 Topic：
$thing/down/property/{ProductID}/{DeviceName} - 响应 Topic：
$thing/up/property/{ProductID}/{DeviceName}
2.请求
-
远程控制请求消息格式：
{ "method": "control", "clientToken": "123", "params": { "power_switch": 1, "color": 1, "brightness": 66 } } -
请求参数说明：
参数 类型 说明 method String control 表示云端向设备发起控制请求 clientToken String 用于上下行消息配对标识 timestamp Integer 属性上报的时间，SDK默认省略 params JSON JSON 结构内为设备上报的属性值 -
sdk回调：
PropertyMessageCallback.method_control_callback
3.响应
-
设备响应远程控制请求消息格式：
{ "method":"control_reply", "clientToken":"123", "code":0, "status":"some message when error" } -
请求参数说明：
参数 类型 说明 method String control_reply表示设备向云端下发的控制指令的请求响应clientToken String 用于上下行消息配对标识 code Integer 0 表示设备成功接收到云端下发的控制指令 status String 当code非0的时候, 提示错误信息 -
sdk接口：
IOT_DataTemplate_PropertyControlReply
获取设备最新上报信息
1.设备从云端接收最新消息使用的 Topic：
- 请求 Topic：
$thing/up/property/{ProductID}/{DeviceName} - 响应 Topic：
$thing/down/property/{ProductID}/{DeviceName}
2.请求
-
请求消息格式：
{ "method": "get_status", "clientToken": "123", "type" : "control", "showmeta": 0 } -
请求参数说明：
参数 类型 说明 method String get_status表示获取设备最新上报的信息clientToken String 消息ID，回复的消息将会返回该数据，用于请求响应消息的对比 type String 表示获取什么类型的信息。 control表示离线下发的消息；report表示设备上报的信息。SDK默认省略，获取所有消息showmeta Integer 标识回复消息是否带 metadata，缺省为0表示不返回metadata，主要是时间戳信息。SDK默认省略 -
sdk接口：
IOT_DataTemplate_PropertyGetStatus
3.响应
-
响应消息格式：
{ "method": "get_status_reply", "clientToken": "123", "code": 0, "type": "report", "data": { "reported": { "power_switch": 1, "color": 1, "brightness": 66 } } } -
响应参数
参数 类型 说明 method String get_status_reply 表示获取设备最新上报信息的 reply 消息 clientToken String 消息 ID，回复的消息将会返回该数据，用于请求响应消息的对比 code Integer 0标识云端成功收到设备上报的属性 type String 表示获取什么类型的信息。control 表示离线下发的消息；report 表示设备上报的信息 data JSON 返回具体设备上报的最新数据内容 -
sdk回调：
PropertyMessageCallback.method_get_status_reply_callback
设备事件上报
1.当设备需要向云端上报事件时，开发平台为设备设定了默认的 Topic：
- 上行请求 Topic：
$thing/up/event/<产品>/<设备> - 上行响应 Topic：
$thing/down/event/<产品>/<设备>
2.请求
-
设备端请求报文示例：
{ "method":"event_post", "clientToken":"123", "version":"1.0", "eventId":"PowerAlarm", "type":"fatal", "timestamp":1212121221, "params":{ "Voltage":2.8, "Percent":20 } } -
请求参数说明：
参数 类型 说明 method String event_post表示事件上报clientToken String 消息 ID，回复的消息将会返回该数据，用于请求响应消息的对比 version String 协议版本，默认为1.0 eventId String 事件的 Id，在物模型事件中定义 type String 事件类型， info：信息；alert：告警；fault：故障timestamp String 事件的参数，在物模型事件中定义 params String 事件的参数，在物模型事件中定义 -
sdk接口：
IOT_DataTemplate_EventPost
3.响应
-
响应消息格式：
{ "method": "event_reply", "clientToken": "123", "version": "1.0", "code": 0, "status": "some message where error", "data": {} } -
响应参数：
参数 类型 说明 method String event_reply表示是云端返回设备端的响应clientToken String 消息 ID，回复的消息将会返回该数据，用于请求响应消息的对比 version String 协议版本，默认为1.0 code Integer 事件上报结果，0表示成功 status String 事件上报结果描述 data JSON 事件上报返回的内容 -
sdk回调：
EventMessageCallback.method_event_reply_callback
设备行为调用
1.当应用通过云端向设备发起某个行为调用时，开发平台为设备行为的处理设定了默认的 Topic：
- 应用调用设备行为 Topic：
$thing/down/action/<产品>/<设备> - 设备响应行为执行结果 Topic：
$thing/up/action/<产品>/<设备>
2.请求
-
应用端发起设备行为调用报文示例：
{ "method": "action", "clientToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10", "actionId": "openDoor", "timestamp": 1212121221, "params": { "userid": "323343" } } -
请求参数说明：
参数 类型 说明 method String action表示是调用设备的某个行为clientToken String 消息 ID，回复的消息将会返回该数据，用于请求响应消息的对比 actionId String actionId是数据模板中的行为标识符，由开发者自行根据设备的应用场景定义timestamp Integer 行为调用的当前时间，SDK默认省略 params String 行为的调用参数，在数据模板的行为中定义 -
sdk回调：
ActionMessageCallback.method_action_callback
3.响应
-
响应消息格式：
{ "method": "action_reply", "clientToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10", "code": 0, "status": "some message where error", "response": { "Code": 0 } } -
响应参数：
参数 类型 说明 method String action_reply表示是设备端执行完指定的行为向云端回复的响应clientToken String 消息 ID，回复的消息将会返回该数据，用于请求响应消息的对比 code Integer 行为执行结果，0表示成功 status String 行为执行失败后的错误信息描述 response String 设备行为中定义的返回参数，设备行为执行成功后，向云端返回执行结果 -
sdk接口：
IOT_DataTemplate_ActionReply