接口作用

如果为设备指定了注册接口,那么设备在加电启动,并成功联网后,会立即开始请求注册接口,以获取下一步连接MQTT服务器所需的地址、用户信息。

当设备与当前MQTT的连接中断(可能是因为断网、也可能是MQTT服务宕机),设备会间隔5-60秒再次尝试连接,如果超过5次连接失败, 则会重新进行设备注册,以获取新的MQTT地址和用户信息。

注册接口可以为设备提供动态的服务器和用户信息,提供了灵活的设备接入机制,可以有效的实现负载均衡,提高服务的可用性。

设备请求此接口后,会优先使用接口返回的服务器信息和用户信息来连接Broker,而不是设备配置的信息(如有)。

如果您只是测试,而且Broker允许匿名连接,可以忽略此节。
如果忽略此节,则在平台配置的消息服务器设置中不要填写“注册接口”项。

实现方法

可在任何设备能访问的网络服务器上,通过web服务来实现此接口。

可以是iis、apache、nginx等任意web容器
可以跟broker在同一台服务器
可在接口中添加日志记录,以供调试使用

可以编程实现以下两种验证方式之一
方式 说明 特点
一机一密 不同的设备
分配不同的用户名和密码
实现较复杂
安全性高
一机一密 不同的产品
分配不同的用户名和密码
实现简单,可使用静态密码
安全性一般
请一定确定设备可以正常访问此接口!

设备请求

设备请求接口时,会携带以下参数,以便接口验证身份。

请求协议:HTTP;请求方式:GET。
参数 / 名称 / 类型 说明
控制台ID
bench
整型
设备所属的控制台ID
控制台ID可在控制台开发设置页面查看。
产品代号
product
字符串
产品代号(Key)为常量,在同一产品的不同设备上,这个值相同,且永不变化
产品Key可在控制台对应的产品详情页查看。
设备ID
device
整型
设备ID平台唯一,每台设备的ID都不相同,且永不变化
设备ID即为贴在设备外壳上的设备标签上的数字ID,在控制台对应的设备详情页也可查看。
时间戳
ts
11位整型
设备发起请求时的时间,此参数的值依赖设备的标准时间, 而标准时间通过设备NTP接口获取。 当NTP接口获取失败时,这个值为0
签名
sign
32位字符串
为判断请求是否有效,可通过签名来判断。 具体算法:
md5(控制台ID + "." + 产品标识 + "." + 设备ID + "." + 设备密码 + "." + 时间戳)
其中前3个参数均为GET参数的值;
设备密码,请到控制台设备详情页查看;
在局域网等场景,也可以不验签

接口返回

设备发起请求后,请根据情况选择是否放行。

当且仅当接口返回的JSON对象的code=200时,请求成功。
如请求失败,设备会间隔5秒,不断发起请求,直至请求成功。
参数 / 名称 说明
状态码
code
1. 返回200:则在下方的data中返回(发放)用户信息:客户端ID、用户名和密码;
2. 返回非200:则为拒绝,设备将间隔5秒不断尝试请求此接口,直至返回200
数据
data
1. code==200时,返回如下:
下方所有输出项均为可选值,如果输出,设备将采纳这些信息; 如果不输出,设备将使用配置信息。
hostBroker的IP地址或域名
(尽量使用IP地址而不是域名,在很多公网线路上,DNS解析会有故障)
portBroker的端口号
topic 设备订阅和发布消息的主题。 不输出,或输出 key / client / 其他。
设备订阅的完整的主题为:{pre}/{type}/{side},其中
{pre}为主题前缀:
输出key(或空)时,主题为:thing/产品代号/设备代号/{type}/{side};
输出client时,主题为:thing/产品代号/设备client/{type}/{side};
输出其他非空字符串时,主题为:输出值/{type}/{side}

{type}为消息类型
{side}为客户端还是服务端:server / client
user
client设备client|客户端ID,对于Broker需要唯一
key设备代号|用户名,登录Broker的用户名
secret设备密码,登录Broker的密码
返回值说明:均为字符串
2. code!=200时:返回{}

返回示例: