保留消息管理
更新时间：2026-05-15
保留消息管理
分页查询 Retain Message 列表
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/retain/pageList | GET |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IoT Core 实例 ID，可在 IoT Core 列表页获取 |
| pageNo | Integer | 是 | QueryParam | 1 | 页码（pageNo >= 1） |
| pageSize | Integer | 是 | QueryParam | 20 | 单页获取数目（1 <= pageSize <= 100） |
输出
成功
http-code：200
| 名称 | 类型 | 描述 |
|---|---|---|
| success | Boolean | 请求是否成功 |
| totalCount | Integer | retain message 总数 |
| pageNo | Integer | 当前页码 |
| pageSize | Integer | 每页大小 |
| results | List<RetainMessageBean> | retain message 列表 |
RetainMessageBean
| 名称 | 类型 | 描述 |
|---|---|---|
| topic | String | MQTT topic |
| message | String | 消息内容（Base64 编码） |
| qos | Integer | QoS 级别（0/1/2） |
| timestamp | Long | 消息保留时间戳（毫秒） |
其他
http-code: 400 参数错误(code:BadRequest) pageNo < 1 或 pageSize 不在 1~100 范围内
示例
请求
Plain Text
1GET http://iot.baidubce.com/v1/iotcore/atmgmqz/retain/pageList?pageNo=1&pageSize=20返回
Plain Text
1{
2 "success": true,
3 "totalCount": 50,
4 "pageNo": 1,
5 "pageSize": 20,
6 "results": [
7 {
8 "topic": "device/sensor/temperature",
9 "message": "eyJ0ZW1wIjogMjUuNX0=",
10 "qos": 1,
11 "timestamp": 1714924800000
12 },
13 {
14 "topic": "device/sensor/humidity",
15 "message": "eyJodW1pZGl0eSI6IDYwfQ==",
16 "qos": 0,
17 "timestamp": 1714924810000
18 }
19 ]
20}获取指定 Topic 的 Retain Message
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/retain | GET |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IoT Core 实例 ID，可在 IoT Core 列表页获取 |
| topic | String | 否 | QueryParam | - | MQTT topic |
输出
成功
http-code：200
| 名称 | 类型 | 描述 |
|---|---|---|
| success | Boolean | 请求是否成功 |
| result | RetainMessageBean | retain message 详情 |
RetainMessageBean
| 名称 | 类型 | 描述 |
|---|---|---|
| topic | String | MQTT topic |
| message | String | 消息内容（Base64 编码） |
| qos | Integer | QoS 级别（0/1/2） |
| timestamp | Long | 消息保留时间戳（毫秒） |
其他
http-code: 400 参数错误(code:BadRequest) topic 为空 http-code: 404 未找到(code:NOT_FOUND) 指定 topic 不存在 retain message
示例
请求
Plain Text
1GET http://iot.baidubce.com/v1/iotcore/atmgmqz/retain?topic=device/sensor/temperature返回
Plain Text
1{
2 "success": true,
3 "result": {
4 "topic": "device/sensor/temperature",
5 "message": "eyJ0ZW1wIjogMjUuNX0=",
6 "qos": 1,
7 "timestamp": 1714924800000
8 }
9}删除指定 Topic 的 Retain Message
接口描述
用于删除指定 topic 上的 retain message。
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/retain | DELETE |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IoT Core 实例 ID，可在 IoT Core 列表页获取 |
| topic | String | 否 | QueryParam | - | 要删除的 MQTT topic |
输出
成功
http-code：200
| 名称 | 类型 | 描述 |
|---|---|---|
| success | Boolean | 请求是否成功 |
| result | Boolean | 删除是否成功 |
其他
http-code: 400 参数错误(code:BadRequest) topic 为空 http-code: 404 未找到(code:NOT_FOUND) 指定 topic 不存在 retain message
示例
请求
Plain Text
1DELETE http://iot.baidubce.com/v1/iotcore/atmgmqz/retain?topic=device/sensor/temperature返回
Plain Text
1{
2 "success": true,
3 "result": true
4}创建/更新 Retain Message
接口描述
创建或更新指定 topic 上的 retain message。如果该 topic 已存在 retain message，则覆盖更新。
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/retain | PUT |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IoT Core 实例 ID，可在 IoT Core 列表页获取 |
| topic | String | 否 | JsonBody | - | MQTT topic |
| message | String | 否 | JsonBody | - | 消息内容（Base64 编码） |
| qos | Integer | 否 | JsonBody | - | QoS 级别，可选值：0、1、2 |
输出
成功
http-code：200
| 名称 | 类型 | 描述 |
|---|---|---|
| success | Boolean | 请求是否成功 |
| result | Boolean | 操作是否成功 |
其他
http-code: 400 参数错误(code:BadRequest) topic 为空、message 为空、或 qos 不在 0~2 范围内 http-code: 403 禁止操作(code:forbidden) 超出 retain message topic 数量上限
示例
请求
Plain Text
1PUT http://iot.baidubce.com/v1/iotcore/atmgmqz/retain
2Content-Type: application/json
3
4{
5 "topic": "device/sensor/temperature",
6 "message": "eyJ0ZW1wIjogMjUuNX0=",
7 "qos": 1
8}返回
Plain Text
1{
2 "success": true,
3 "result": true
4}异常返回
对于请求异常或者服务器异常，服务有统一的返回格式。
| 名称 | 类型 | 描述 |
|---|---|---|
| requestId | String | 代表这次请求的 id |
| code | String | 异常的类型 |
| message | String | 异常的详细信息 |
http 返回码遵循 http 协议，以下是统一的错误码：
| 错误码 | code | 描述 |
|---|---|---|
| 400 | BadRequest | 参数错误；任意请求参数不符合规范 |
| 403 | forbidden | 禁止访问；对当前 IoT Core 没有访问权限，或 retain message topic 数量超限 |
| 404 | NOT_FOUND | 未找到；指定 topic 不存在 retain message |
| 429 | TooManyRequests | 请求频率超限；请降低请求频率后重试 |
| 500 | INTERNAL_SERVER_ERROR | 内部出错；此状态时客户端可重试 |
| 501 | NOT_SUPPORTED | 当前实例存储后端不支持此操作 |
异常返回示例
Plain Text
1{
2 "requestId": "60ea5d26-2fe3-4841-8541-5a67eae683ea",
3 "code": "BadRequest",
4 "message": "topic can not be empty."
5}评价此篇文章