基于HTTP协议建立连接

HTTP(Hypertext Transfer Protocol )协议接入是指通过HTTP的方式将设备接入到UCloud IoT-Core通信云平台,将数据上传到云端。

由于HTTP的采用请求/响应的模型,所以HTTP仅能用于数据上报,不能用于命令的下发。

HTTP连接注意事项

  • HTTP接入仅支持HTTPS协议,TLS为V1.2版本;
  • CA证书为国际授信的域名证书,也可以直接下载CA证书
  • HTTP请求只支持POST方式;
  • 基于MQTT的Topic规范,数据上报到MQTT的某个Topic;
  • 上报数据请求URL:https://http-cn-sh2.iot.ucloud.cn/topic/${topic}。其中${topic}的值是指具备发布权限的Topic。不支持以 ?query_String=xxx 格式传参;
  • HTTP接入注册需要已知${DeviceSecret},不支持使用${ProductSecret}进行注册;
  • 数据上行传输的数据大小限制为 128 KB;
  • 设备静态注册请求的HTTP header中的Content-Type必须为 application/json
  • 数据上报请求的HTTP header中的Content-Type必须为 application/octet-stream
  • 设备注册成功后,HTTP服务会返回Token,有效期为7天,需要做好Token续期服务;

具体流程:

1. 获取到设备的注册凭证:产品序列号设备序列号设备密码,分别表示为${ProductSN}${DeviceSN}${DevSecret}

2. 下载TLS证书,下载根证书

3. 设备注册。通过HTTP POST请求获取上报数据的Token,见返回参数

POST /auth HTTP/1.1
Host: http-cn-sh2.iot.ucloud.cn
Content-Type: application/json
Authorization: 47b0194e52ed1d1630830b66709b906a1e201ba410101cfaf9381bbde53a0d85
body: {"ProductSN":"ZG1EvTEa7NN","DeviceSN":"NlwaSPXsCpTQuh8FxBGH","Timestamp":"1501668289957"}

参数说明

参数说明
Method请求方法。只支持 POST 方法。
URL/auth,URL 地址
HostHTTP服务地址
Content-Typebody 数据的编码格式。目前只支持 application/json
Authorization使用设备密码签名。签名计算格式为 HMAC-SHA256(DeviceSecret, body)
body设备认证信息。JSON 数据格式。具体信息,请参见下表 body 参数。

body 参数

参数名称必选类型描述
ProductSNstring产品序列号
DeviceSNstring设备序列号
Timestampint64时间戳(如填写时间误差不超过 3600 秒)

返回参数

{
  "RetCode": 0,
  "Message": "Success",
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJEZXZpY2VTTiI6InRlc3QxIiwiUHJvZHVjdFNOIjoiZzR3ZmFycTMweXp4YXkyMyIsImV4cCI6MTU2NzA1ODg5OSwiaWF0IjoxNTY2NDU0MDk5fQ.wN1XNVciI27nTeIqCjbYKdmTaifJrGJm_DmDDpIoabs"
}

错误码

RetCodeMessage备注
130Service is temporarily unavailable, we are working hard to restore it, please retry later服务暂时不可用。
171Signature error签名错误。
230Parameter error, please reenter请求的参数异常。
100070Timestamp error时间戳错误,误差超过限制。
100071Product or device not exist产品或设备不存在。
100072Device disabled设备已禁用。

4. 上报数据。将数据发送数据到某个 Topic。
HTTP平台支持发布权限的自定义或系统Topic。

POST /topic/${topic} HTTP/1.1
Host: http-cn-sh2.iot.ucloud.cn
Password: ${token}
Content-Type: application/octet-stream
body: ${your_data}

参数说明

参数说明
Method请求方法。只支持 POST 方法。
URL/topic/${topic}。其中,变量 ${topic} 需替换为数据发往的目标Topic。
Hostendpoint 地址
Content-Typebody 数据的编码格式。目前只支持 application/octet-stream
Password放在Header中的参数,取值为调用设备认证接口 auth 返回的 token 值。
body发往 ${topic} 的数据内容,长度不超过 128 KB。

返回参数

{
  "RetCode": 0,
  "Message": "Success",
  "MessageID": "349022219378098176"
}

错误码

RetCodeMessage备注
130Service is temporarily unavailable, we are working hard to restore it, please retry later服务暂时不可用。
230Parameter error, please reenter请求的参数异常。
100071Product or device not exist产品或设备不存在。
100072Device disabled设备已禁用。
100073Check token errortoken错误。需重新调用auth进行鉴权,获取token。
100074Token is expiredtoken过期。需重新调用auth进行鉴权,获取token。
100075ACL FailedACL 失败,无相应 topic 权限。
100076Maximum request length exceededbody 长度超过限制。
100077Publish message Failed数据发送失败。