## 简介

用户创建完产品后即可定义数据模板，基于导出数据模板json配置文件通过SDK提供的脚本工具可以自动生成数据模板配置代码，设备调试阶段的在线调试会接收设备的上报数据并可在控制台下发控制指令到设备进行调试。本文档介绍数据模板协议。

## 数据模板协议

### 概述
物联网开发平台定义了一套通用的方法，实现设备的统一描述、统一控制，进而提供数据的流转和计算服务，实现不同设备的互联互通、数据的流转和融合，助力应用落地。

产品定义了数据模板以后，设备可以按照数据模板中的定义上报属性、事件，并可对设备下发远程控制指令，即对可写的设备属性进行修改。数据模板的管理详见 [产品定义](https://cloud.tencent.com/document/product/1081/34739)。数据模板协议包括了以下几部分。

- 设备属性上报：设备端将定义的属性根据设备端的业务逻辑向云端上报。
- 设备远程控制：从云端向设备端下发控制指令，即设置设备可写属性。
- 获取设备最新上报信息：获取设备最新的上报数据。
- 设备事件上报：设备可根据定义的数据模板中的事件，当事件被触发，则根据设备事件上报的协议上报告警、故障等事件信息。
- 设备行为：云端可以通过 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
		}
}
```
 - 参数说明：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>method</td>
      <td>String</td>
      <td>report 表示设备属性上报。</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>用于上下行消息配对标识</td>
   </tr>
   <tr>
      <td>timestamp</td>
      <td>Integer</td>
      <td>属性上报的时间</td>
   </tr>
   <tr>
      <td>params</td>
      <td>JSON</td>
      <td>JSON 结构内为设备上报的属性值</td>
   </tr>
</table>
3. 响应
 - 云端返回设备端报文示例：
```
{
		"method":"report_reply",
		"clientToken":"123",
		"code":0,
		"status":"some message wher error"
}
```
 - 响应参数说明：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>method</td>
      <td>String</td>
      <td>report_reply 表示云端接收设备上报后的响应报文</td>
   </tr>
  <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>用于上下行消息配对标识</td>
   </tr>
   <tr>
      <td>code</td>
      <td>Integer</td>
      <td>0表示云端成功收到设备上报的属性</td>
   </tr>
   <tr>
      <td>status</td>
      <td>String</td>
      <td>当code非0的时候, 提示错误信息</td>
   </tr>   
</table>


### 设备远程控制

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	
        }
}
```
 - 请求参数说明：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>method</td>
      <td>String</td>
      <td>control 表示云端向设备发起控制请求</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>用于上下行消息配对标识</td>
   </tr>
   <tr>
      <td>params</td>
      <td>JSON</td>
      <td>JSON 结构内为设备上报的属性值</td>
   </tr>
</table>
3. 响应
 - 设备响应远程控制请求消息格式：
```
{
		"method":"control_reply",
		"clientToken":"123",
		"code":0,
		"status":"some message wher error"
}
```
 - 请求参数说明：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>control_reply</td>
      <td>String</td>
      <td>表示设备向云端下发的控制指令的请求响应</td>
   </tr>
   <tr>
      <td>code</td>
      <td>Integer</td>
      <td>0表示设备成功接收到云端下发的控制指令</td>
   </tr>
   <tr>
      <td>status</td>
      <td>String</td>
      <td>当 code 非0的时候, 提示错误信息</td>
   </tr>   
</table>



### 获取设备最新上报信息

1. 设备从云端接收最新消息使用的 Topic：
   - 请求 Topic： `$thing/up/property/{ProductID}/{DeviceName}`
   - 响应 Topic： `$thing/down/property/{ProductID}/{DeviceName}`
2. 请求
 - 请求消息格式：
```
{
		"method": "get_status",
		"clientToken": "123",
		"type" : "report", 
		"showmeta": 0
}
```
 - 请求参数说明：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>get_status</td>
      <td>String</td>
      <td>get_status 表示获取设备最新上报的信息</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>消息 ID，回复的消息将会返回该数据，用于请求响应消息的对比。</td>
   </tr>
	 <tr>
      <td>type</td>
      <td>String</td>
      <td>表示获取什么类型的信息。report 表示设备上报的信息</td>
   </tr>
	   <tr>
      <td>showmeta</td>
      <td>Integer</td>
      <td>标识回复消息是否带 metadata，缺省为0表示不返回 metadata</td>
   </tr>
</table>
3. 响应
 - 响应消息格式： 

```
{
   	"method": "get_status_reply",
       "code": 0,
	   "clientToken": "123",
	   "type": "report",
   	"data": {
		   "report": {
		         "power_switch": 1,
                 "color": 1,
                 "brightness": 66	
		   }
    	}
}
```

 - 响应参数
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>get_status_reply</td>
      <td>String</td>
      <td>表示获取设备最新上报信息的 reply 消息</td>
   </tr>
	 <tr>
      <td>code</td>
      <td>Integer</td>
      <td>0标识云端成功收到设备上报的属性</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>消息 ID，回复的消息将会返回该数据，用于请求响应消息的对比。</td>
   </tr>
	 <tr>
      <td>type</td>
      <td>String</td>
      <td>表示获取什么类型的信息。report 表示设备上报的信息</td>
   </tr>
	   <tr>
      <td>data</td>
      <td>JSON</td>
      <td>返回具体设备上报的最新数据内容</td>
   </tr>
</table>



### 设备事件上报

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
        }
}
```
 - 请求参数说明：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>method</td>
      <td>String</td>
      <td>event_post 表示事件上报。</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>消息 ID，回复的消息将会返回该数据, 用于请求响应消息的对比。</td>
   </tr>
   <tr>
      <td>version</td>
      <td>String</td>
      <td>协议版本，默认为1.0。</td>
   </tr>
   <tr>
      <td>eventId</td>
      <td>String</td>
      <td>事件的 ID，在数据模板事件中定义。</td>
   </tr>
   <tr>
      <td>params</td>
      <td>String</td>
      <td>事件的参数，在数据模板事件中定义。</td>
   </tr>
   <tr>
      <td>timestamp</td>
      <td>Integer</td>
      <td>事件上报的时间，不填写该字段表示就使用事件上报本身的时间。</td>
   </tr>
</table>
3. 响应
 - 响应消息格式： 

```
{
		"method": "event_reply",
		"clientToken": "123",
		"version": "1.0",
		"code": 0,
		"status": "some message wher error",
		"data": {}
}
```

 - 响应参数：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>method</td>
      <td>String</td>
      <td>event_reply 表示是云端返回设备端的响应。</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>消息 ID，回复的消息将会返回该数据, 用于请求响应消息的对比。</td>
   </tr>
   <tr>
      <td>version</td>
      <td>String</td>
      <td>协议版本，默认为1.0。</td>
   </tr>
   <tr>
      <td>code</td>
      <td>Integer</td>
      <td>事件上报结果，0表示成功。</td>
   </tr>
   <tr>
      <td>status</td>
      <td>String</td>
      <td>事件上报结果描述。</td>
   </tr>
   <tr>
      <td>data</td>
      <td>JSON</td>
      <td>事件上报返回的内容。</td>
   </tr>
</table>


### 设备行为调用

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"	
	    }
}
```
 - 请求参数说明：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>method</td>
      <td>String</td>
      <td>action 表示是调用设备的某个行为</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>消息 ID，回复的消息将会返回该数据, 用于请求响应消息的对比。</td>
   </tr>
   <tr>
      <td>actionId</td>
      <td>String</td>
      <td>actionId 是数据模板中的行为标识符，由开发者自行根据设备的应用场景定义</td>
   </tr>  
     <tr>
      <td>timestamp</td>
      <td>Integer</td>
      <td>行为调用的当前时间</td>
   </tr>
   <tr>
      <td>params</td>
      <td>String</td>
      <td>行为的调用参数，在数据模板的行为中定义。</td>
   </tr> 
</table>
3. 响应
 - 响应消息格式：  
```
{
		"method": "action_reply",
		"clientToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10",
		"code": 0,
		"status": "some message wher error",
		"response": {
		"Code":  0
        }
}
```

 - 响应参数：
<table>
   <tr>
      <th>参数</th>
      <th>类型</th>
      <th>说明</th>
   </tr>
   <tr>
      <td>method</td>
      <td>String</td>
      <td>action_reply 表示是设备端执行完指定的行为向云端回复的响应</td>
   </tr>
   <tr>
      <td>clientToken</td>
      <td>String</td>
      <td>消息 ID，回复的消息将会返回该数据, 用于请求响应消息的对比。</td>
   </tr>
 
   <tr>
      <td>code</td>
      <td>Integer</td>
      <td>行为执行结果，0表示成功。</td>
   </tr>
   <tr>
      <td>status</td>
      <td>String</td>
      <td>行为执行失败后的错误信息描述。</td>
   </tr>
   <tr>
      <td>response</td>
      <td>JSON</td>
      <td>设备行为中定义的返回参数，设备行为执行成功后，向云端返回执行结果</td>
   </tr>
</table>