物接入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 需要上传的数据
    上一篇
    快速入门
    下一篇
    设备型项目