AMQP客户端接入说明

协议版本说明

AMQP协议标准的详细介绍，请参见AMQP协议标准。

阿里云物联网平台服务端订阅仅支持AMQP 1.0版的协议标准。

连接认证过程

1. 首先，AMQP客户端与物联网平台经过三次握手建立TCP连接，然后进行TLS握手校验。
   说明 为了保障安全，接收方必须使用TLS加密，不支持非加密的TCP传输。
2. 客户端请求建立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存在保活心跳，只需保证主进程不退出即可。
3. 客户端向云端发起请求，建立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），否则将会连接失败。授权方法请参见授权子账号访问物联网平台。
  timestamp	是	当前时间。Long类型的毫秒值时间戳。

  表 3. password参数说明

  参数	是否必需	说明
  signMethod	是	签名算法。请使用userName中指定的签名算法计算签名值，并转为base64字符串。
  stringToSign	是	待签名的字符串。 将需要签名的参数的键值对按照首字母字典排序，并在键值间添加等号（=）；参数间添加与号（&），拼接成待签名的字符串。 需要签名的参数为：authId和timestamp。 待签名的字符串为stringToSign = authId=${accessKey}&timestamp=1573489088171。
  accessSecret	是	您的阿里云账号的AccessKey Secret。 登录物联网平台控制台，将鼠标移至账号头像上，然后单击AccessKey管理，获取AccessKey。 说明 如果使用RAM用户AccessKey ID，您需要给该RAM用户授予管理物联网平台的权限（AliyunIOTFullAccess），否则将会连接失败。授权方法请参见授权子账号访问物联网平台。

接入示例

您可以使用以下语言的AMQP客户端接入示例。示例中的参数配置，请参见连接配置说明。

• Java SDK接入示例
• .NET SDK接入示例
• Node.js SDK接入示例
• Python 2.7 SDK接入示例
• Python3 SDK接入示例
• PHP SDK接入示例
• Go SDK接入示例

接入过程中，您可能会遇到消息相关的错误码。更多信息，请参见消息相关错误码。

接收云端推送的消息

客户端和云端之间的Receiver Link建连成功后，云端就可以在这条Link上向AMQP客户端推送消息。

云端推送的消息：

• 消息体：消息的payload为二进制格式。
• 消息的业务属性，如消息Topic和Message ID等，需要从AMQP协议的Application Properties中获取。格式为key:value。

  Key	含义
  topic	消息Topic。
  messageId	消息ID。
  generateTime	消息生成时间。 说明 消息生成时间generateTime不能作为判断消息顺序的依据。

消息回执：

按照AMQP协议的定义，客户端需要给云端回执（AMQP协议上一般称为settle），通知云端消息已经被成功接收。AMQP客户端通常会提供自动回执模式（推荐）和手动回执模式。具体请参考相应的客户端的使用说明。