所有文档

          物接入 IoT Hub

          通用功能

          连接建立与断开事件订阅

          当一个 MQTT 连接建立或者断开时,会触发一条系统主题的通知。订阅此通知可获取连接建立及断开事件。

          设备型项目可通过超级权限订阅的连接此类别相关主题。

          对应主题及消息详情如下:

          获取连接建立事件

          订阅 $baidu/sys/event/connect

          消息格式:

          {
           "deviceName": "a",
           "connectionType": "CONNECT",
           "version": 79974,
           "timestamp": 1534237636338,
           "clientId": "client-283216bb-26b6-4779-9506-4d10f6a49c5f"
          }

          获取连接断开事件

          订阅 $baidu/sys/event/disconnect

          消息格式:

          {
          "deviceName": "a",
           "connectionType": "DISCONNECT",
           "version": 79974,
           "timestamp": 1534237636338,
           "clientId": "client-283216bb-26b6-4779-9506-4d10f6a49c5f"
          }

          持久化会话和消息缓存

          物接入支持 MQTT 标准中的会话持久化及消息缓存机制。

          如果客户端在连接的时候指定Clean Session=false,那这个会话将成为一个持久化会话。如果客户端异常离线,物接入将缓存“QoS=1”的消息,待客户端重新连接后将消息发送至客户端。需要注意以下情况:

          • 消息只能缓存24小时。
          • 如果缓存消息的数量较大,推荐使用百度Kafka服务。
          • 客户端重新连接时Clean Session需置为False(flag=0)。 如果Clean Session为True(flag=1),物接入会丢弃已经缓存任何会话状态信息,创建一个新的会话连接。

          如下例所示:

          1. 控制用户和实体设备1正常接入物接入,控制用户发布“QoS=1”的消息Message001,实体设备1可以正常接收到。
          2. 如果实体设备1异常离线,此时物接入将缓存所有发送至该用户的消息。
          3. 此时如果有其它订阅了相同主题的设备连接至物接入,可以正常接收到控制用户新发送的消息,但无法接收到之前被缓存的消息。
          4. 实体设备1重新接入物接入,根据状态的不同,物接入有以下两种处理方式: 如果Clean Session为True,物接入会丢弃已经缓存任何会话状态信息,为实体设备1创建一个新的会话连接。 如果Clean Session置为False,此时物接入将所有缓存的消息转发至实体设备1。

          保留(Retain)消息

          物接入支持 MQTT 标准中的保留消息机制。

          如果 Publish 消息固定头部 Retain 标记为1,物接入会持久保存此消息,直到该消息被新的 Publish 消息(Retain=1)覆盖或用户主动清除该消息。

          对于“Retain=1”的消息,物接入不但会将该消息发送给所有当前的订阅者,同时新的接入用户也会收到该消息,如下图所示:

          1. 控制用户和实体设备1正常接入物接入,控制用户发布“Retain=1”的消息Message001,实体设备1可以正常接收到并且物接入持久保存该消息。
          2. 新实体设备2连接后,物接入持久保存的消息发布给新接入用户。

          HTTP方式更新主题

          除标准 MQTT 方式以外,您也可以通过 HTTP 方式更新主题。针对不同地域,入口域名不同,对应域名如下:

          • 北京:api.mqtt.iot.bj.baidubce.com
          • 广州:api.mqtt.iot.gz.baidubce.com

          出于安全考虑,建议使用HTTPS访问。

          URI HTTP 方式 Content Type Return Type
          https://api.mqtt.iot.gz.baidubce.com/v1/proxy?qos=0&topic=yourTopic&retain=false POST application/octet-stream application/json;charset=UTF-8

          请求参数

          名称 是否必选 含义
          qos Y 该消息的QoS取值,可选0或1
          topic Y topic名称,客户端将向指定的topic发布消息
          retain N retain标记,详细介绍请参看保留消息

          请求头参数

          名称 是否必选 含义
          auth.username Y 用户名,即:影子名称/用户名称
          auth.password Y 密码,即:创建身份时获得的密钥

          发布的具体消息内容放在HTTP Content中,可以是二进制消息(向设备型项目主题Publish消息,需符合指定的json格式)。消息长度不大于32K。

          请求示例

          POST /v1/proxy?qos=0&topic=$baidu/iot/shadow/test/update&retain=false HTTP/1.1
          host: api.mqtt.iot.gz.baidubce.com
          content-type: application/octet-stream
          
          auth.username: jka2njk/test
          auth.password: j92NcN8Czs1w3ifY
          ------------------------------------------
          Content:
          {
            "reported": {
              "key": value
             }
          }

          成功:201,失败:4XX or 5XX

          CoAP 接入接口及数据结构定义

          目前仅在广州区域开放申请,北京区域暂未上线。

          服务地址 coap://endpointName.coap.gz.baidubce.com

          鉴权接口

          使用此接口获取数据上报时所需的鉴权 token

          请求示例

          POST /auth
          Host: {endpointName}.coap.gz.baidubce.com
          Port: 5683
          Accept: text/plain
          Content-Format: application/json
          payload: {"projectId":"abcdefg","adpType":"ThingIdp","accessKey":"accessKey","signature":"e49428d7ca3ea920978fbe96656b82ca","dateTime":1557741315043,"algo":"MD5"}

          参数说明

          参数 是否必需 说明
          Method POST
          URL /auth
          Host endpointName.coap.gz.baidubce.com
          Port 当前仅支持非DTLS,端口号:5683
          Accept 鉴权返回token默认为二进制数据,不需要编码,若指定为text/plain,则返回字符串token
          Content-Format 上传数据的编码方式。application/json
          Payload 用户提供的鉴权信息:
          {
          projectId : endpointUuid
          adpType : "ThingIdp"
          accessKey : username
          dateTime : 可选,格式为长整型UNIX TimeStamp
          algo : 可选,使用的加密算法,默认为MD5
          signature : 使用指定的加密算法加密
          accessKey+"&"+dateTime+"&"+algo+secretKey生成的签名(dateTime可为0,algo默认的MD5也需要被加密)
          }

          返回值

          参数 说明
          Return token,服务器生成的授权token

          数据上报接口

          使用此接口向指定 Topic 发布请求,可用于数据上报。

          请求示例

          POST /topic/{yourTopic}?token={yourToken}
          Host: {endpointName}.coap.gz.baidubce.com
          Port: 5683
          Accept: application/json
          Content-Format: application/json
          payload: {
            "reported": {
              "yourkey": "yourvalue"
             }
          }

          请求参数说明

          参数 是否必需 说明
          Method POST
          URL /topic/{yourTopic}?token={yourToken}
          其中{yourTopic}为用户在物接入中查看或配置的MQTT主题
          {yourToken}为 auth 返回的 token,当option中有传输token时此处可省略
          Host endpointName.coap.gz.baidubce.com
          Port 端口,非DTLS:5683,DTLS:5684
          Accept 设备接收的数据编码方式。application/json
          Content-Format 上传数据的编码方式。application/json
          CustomOptions 当使用 URL 中 token 参数时此项非必需 2080:token;
          payload 需要上传的数据
          上一篇
          快速入门
          下一篇
          设备型项目