JieIOT HTTP标准协议

对于一些非常单一的应用场景，比如只需要定期采集上报数据，不论是快速开发原型，还是小规模的应用，设备使用 HTTP 接入云平台也是不错的选择。

事实上，将 HTTP 协议的简单易用发挥到极致，便是 CoAP 协议，对于低功耗设备的单一数据上报，使用 CoAP 更加符合要求，这在相关章节会有介绍。

设备 HTTP 接入点

接入类型	用途	接入点示例
HTTP	普通方式，适合大多数普通设备或资源受限设备	http:// <endpoint>
HTTPs	基于 SSL 证书的加密传输方式，适合对通信安全要求严格的设备	https:// <endpoint>

设备访问 API 一览

对于不同的消息类型，API 如下：

消息类型	Method	URL
上报属性	POST	/device/v1/property/post?dn=${deviceLoginName}&ds=${deviceSecret}
上报事件	POST	/device/v1/event/post?dn=${deviceLoginName}&ds=${deviceSecret}

参数	类型	说明	必选	备注
${deviceLoginName}	string	设备 ID	是	来源设备登录名。
${deviceSecret}	string	设备 ID	是	来源设备密码。

HTTP请求报文格式

属性上报发送报文格式

设备主动向云端上报设备属性值。

接口	Method	URL
HTTP	POST	/device/v1/property/post?dn=${deviceLoginName}&ds=${deviceSecret}

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "property/post",
	"sys" :{
		"ack": 1
	},
	"data":{
    	"color":{
        	"value":"red",
          	"time": 1626197189638  
        }, 
        "brightness":{
            "value":80,
            "time": 1626197189638
        }
	}
}

支持不带时间戳，默认使用设备上报时间。

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "property/post",
	"data":{
    	"color":"red",
        "brightness":80
	}
}

参数说明

参数	类型	说明	必选	备注
${deviceLoginName}	string	设备 ID	是	来源设备登录名。
${deviceSecret}	string	设备 ID	是	来源设备密码。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
sys	object	系统参数	否	控制消息的系统行为。
sys.ack	number	属性上报应答行为	否	默认情况下设备属性上报后云端不会返回应答消息，但可以通过 ack 参数改变这一默认行为。 0：不做应答，默认值。 1：处理之后返回应答消息。
data	object	上报的属性值集合	是	key 为属性 Key，value 为对象（属性值和属性变更时间戳）或属性值。
data.${key}	object	属性上报对象	是	key 为属性 Key。
data.${key}.time	number	属性变更时间戳	是	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.${key}.value	object	属性上报值	是	具体的属性值。

属性上报响应报文格式

云端处理上报后，对属性上报消息进行响应

{
	"msgId":"45lkj3551234",
    "time":1626197189640,
	"method": "property/post_reply",
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${deviceLoginName}	string	设备 ID	是	来源设备登录名。
${deviceSecret}	string	设备 ID	是	来源设备密码。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的上报消息的 msgId 保持一致，通过 msgId 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
code	number	响应状态码	否	0 代表成功，默认值。非 0 代表失败。

状态码说明

状态码	说明
0	默认状态，代表成功。
101003	数据格式错误。
101004	设备不存在。
102002	设备关联的模型未定义。
102003	设备关联的属性未定义。
102006	数据校验失败。

事件上报设备发送消息

设备主动向云端上报设备事件触发的消息。

接口	Method	URL
HTTP	POST	/device/v1/event/post?dn=${deviceLoginName}&ds=${deviceSecret}

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "event/post_reply",
	"data":{
      	"key":"testEvent",
      	"time":1626197189630,   //10 位秒级或 13 位毫秒级事件发生时间戳
      	"value": 123
	}
}

参数说明

参数	类型	说明	必选	备注
${deviceLoginName}	string	设备 ID	是	来源设备登录名。
${deviceSecret}	string	设备 ID	是	来源设备密码。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
data	object	事件上报参数	是	事件上报参数。
data.key	string	事件 key	是	事件的模型定义 key。
data.time	number	事件发生时间	否	事件发生时间的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data.value	object	事件模型值	否	事件模型的值。

事件上报响应报文格式

云端接收事件消息之后，对消息进行响应。

{
	"msgId":"45lkj3551234",
    "time":1626197189640,
	"method": "event/post_reply",
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${productKey}	string	设备 ID	是	事件上报的目标设备的所属产品 Key。
${deviceKey}	string	设备 ID	是	事件上报的目标设备的 Key。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的事件触发消息的 msgId 保持一致，通过 msgId 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
code	number	响应状态码	否	0 代表成功，默认值。非 0 代表失败。

状态码说明

状态码	说明
0	默认状态，代表成功。
1003	数据格式错误。
2121	批量上报部分数据处理失败。
2122	批量上报完全处理失败。
2123	批量上报子设备个数超过限制，目前子设备个数上限不能超过 20 个。