通用功能

连接建立与断开事件订阅

当一个 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.pasword: 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 需要上传的数据