控制台配置完AMQP服务端订阅后,您需要参考本文将AMQP客户端接入物联网平台。成功接入后,在您的服务端运行AMQP客户端,即可接收设备消息。
协议版本说明
AMQP协议标准的详细介绍,请参见AMQP协议标准。
阿里云物联网平台服务端订阅仅支持AMQP 1.0版的协议标准。
连接认证过程
- 首先,AMQP客户端与物联网平台经过三次握手建立TCP连接,然后进行TLS握手校验。
说明 为了保障安全,接收方必须使用TLS加密,不支持非加密的TCP传输。
- 客户端请求建立Connection。
连接认证方式为PLAIN-SASL,可以理解为用户名(userName)和密码(password)认证。云端认证userName和password通过后,建立Connection。
此外,根据AMQP协议,客户端建连时,还需在Open帧中携带心跳时间,即AMQP协议的idle-time-out参数。心跳时间单位为毫秒,取值范围为30,000~300,000。如果超过心跳时间,Connection上没有任何帧通信,物联网平台将关闭连接。SDK不同,idle-time-out参数设置方法不同。具体设置方法,请参见各语言SDK示例文档。说明 使用阿里云提供的SDK,建立连接后,无需发送PING包维持连接。SDK存在保活心跳,只需保证主进程不退出即可。 - 客户端向云端发起请求,建立Receiver Link(即云端向客户端推送数据的单向通道)。
客户端建立Connection成功后,需在15秒内完成Receiver Link的建立,否则物联网平台会关闭连接。
建立Receiver Link后,客户端成功接入物联网平台。
说明- 一个Connection上只能创建一个Receiver Link,不支持创建Sender Link,即只能由云端向客户端推送消息,客户端不能向云端发送消息。
- Receiver Link在有的SDK中名称不同,例如在有的SDK上称为MessageConsumer,请根据具体SDK设置。
连接配置说明
AMQP客户端接入物联网平台的连接地址和连接认证参数说明如下:
- 接入域名:
- 公共实例的接入域名:
${uid}.iot-amqp.${regionId}.aliyuncs.com
。表 1. 公共实例域名中的变量说明 字段 说明 uid 您的阿里云账号ID。 可登录物联网平台控制台,单击账号头像,跳转至安全设置页面查看。
regionId 您的物联网平台服务所在地域ID。 在物联网平台控制台左上方可查看地域。RegionId的表达方法,请参见地域和可用区。
说明- SDK中的${YourHost}即为接入域名。
- 企业版实例接入时,请确保产品和设备已创建在对应的企业版实例下。
- 公共实例的接入域名:
- 端口:
- 对于Java、.NET、Python 2.7、Node.js、Go客户端:端口号为5671。
- 对于Python3、PHP客户端:端口号为61614。
- 客户端身份认证参数:
userName = clientId|iotInstanceId=${iotInstanceId},authMode=aksign,signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171| password = signMethod(stringToSign, accessSecret)
表 2. userName参数说明 参数 是否必需 说明 clientId 是 表示客户端ID,建议使用您的AMQP客户端所在服务器UUID、MAC地址、IP等唯一标识。长度不可超过64个字符。 登录物联网平台控制台,在查看,消费组详情页将显示该参数,方便您识别区分不同的客户端。
,单击消费组对应的iotInstanceId 否 实例ID。仅企业版实例需要传入。公共实例下,不传此参数。 authMode 是 鉴权模式。目前仅支持aksign模式。 signMethod 是 签名算法。可选:hmacmd5、hmacsha1和hmacsha256。 consumerGroupId 是 消费组ID。 登录物联网平台控制台,在
查看您的消费组ID。authId 是 认证信息。在aksign鉴权模式下,authId取值为您的阿里云账号AccessKey ID。 登录物联网平台控制台,将鼠标移至账号头像上,然后单击AccessKey管理,获取AccessKey。
说明 如果使用RAM用户AccessKey ID,您需要给该RAM用户授予管理物联网平台的权限(AliyunIOTFullAccess),否则将会连接失败。授权方法请参见授权RAM用户访问物联网平台。timestamp 是 当前时间。Long类型的毫秒值时间戳。 表 3. password参数说明 参数 是否必需 说明 signMethod 是 签名算法。请使用userName中指定的签名算法计算签名值,并转为base64字符串。 stringToSign 是 待签名的字符串。 将需要签名的参数的键值对按照首字母字典排序,并在键值间添加等号(=);参数间添加与号(&),拼接成待签名的字符串。
需要签名的参数为:authId和timestamp。
待签名的字符串为
stringToSign = authId=${accessKey}×tamp=1573489088171
。accessSecret 是 您的阿里云账号的AccessKey Secret。 登录物联网平台控制台,将鼠标移至账号头像上,然后单击AccessKey管理,获取AccessKey。
说明 如果使用RAM用户AccessKey ID,您需要给该RAM用户授予管理物联网平台的权限(AliyunIOTFullAccess),否则将会连接失败。授权方法请参见授权RAM用户访问物联网平台。
接入示例
您可以使用以下语言的AMQP客户端接入示例。示例中的参数配置,请参见连接配置说明。
接入过程中,您可能会遇到消息相关的错误码。更多信息,请参见消息相关错误码。
接收云端推送的消息
客户端和云端之间的Receiver Link建连成功后,云端就可以在这条Link上向AMQP客户端推送消息。
云端推送的消息:
- 消息体:消息的payload为二进制格式。
- 消息的业务属性,如消息Topic和Message ID等,需要从AMQP协议的Application Properties中获取。格式为
key:value
。Key 含义 topic 消息Topic。 messageId 消息ID。 generateTime 消息生成时间。 说明 消息生成时间generateTime不能作为判断消息顺序的依据。
消息回执:
按照AMQP协议的定义,客户端需要给云端回执(AMQP协议上一般称为settle),通知云端消息已经被成功接收。AMQP客户端通常会提供自动回执模式(推荐)和手动回执模式。具体请参考相应的客户端的使用说明。
- 实时消息直接推送。
- 进入堆积列队的消息
由于消费客户端离线、消息消费慢等原因,消息不能实时消费,而进入堆积队列。
- 消费客户端重新上线并恢复稳定消费能力后,云端重试推送堆积消息。
- 如果客户端对重试推送的消息消费失败,可能导致堆积队列阻塞。按大约一分钟间隔,云端向客户端再次重试推送。
- 设备上下线消息:
收到消息的时间不是实际设备上下线时间。设备上下线时间,请按照lastTime判断。
例如,您依次收到3条消息:- 上线:
2018-08-31 10:02:28.195
- 下线:
2018-08-31 10:01:28.195
- 下线:
2018-08-31 10:03:28.195
关于消息中参数的更多信息,请参见数据格式。
- 上线:
- 其他类型的消息:
您需要在业务层,给消息增加序列号。根据接收到消息中的序列号,幂等判断消息是否需要处理。