设备管理
更新时间：2025-08-21
设备管理
创建设备
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/device/new | POST |
输入
| 名称 | 类型 | 是否可选 | 默认值 | 描述 |
|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | iotCoreId，通过管理控制台获取 |
| name | String | 否 | JsonBody | Device在一个IoTCore内的唯一名称。允许1~40个字符，接受字母、数字、中线（-）、下划线（_），区分大小写（follow MQTT topic 标准） |
| templateId | String | 否 | JsonBody | 使用的设备主题模板的Id，暂时通过管理控制台获取，以后会开放接口，用于管理主题权限 |
| authType | String | 是 | JsonBody | 认证类型，可选值：SIGNATURE：是用name/SK的方式认证身份，其中name字段对应设备唯一的名称。CERTIFICATE：证书认证 |
| desc | String | 是 | JsonBody | Device的描述信息0-128任意字符 |
| tags | Map<String, String> | 是 | JsonBody | 设备的标签信息，可用于参与鉴权运算。标签key限制如下：1-40字符；字符开头；接受字符和数字；不能和保留字相同（见下文），标签value限制如下：1-40字符，接受字符和数字：设备在创建好会有一个固定标签:key=$name，value={name}（name即设备名）。该标签无法删除和修改，也不会显示在标签列表里。 |
tagkey保留字
Plain Text
1"s", "sub", "subject",
2"o", "obj", "objective",
3"e", "env", "environment",
4"true", "false"输出
成功
http-code: 201 authType为SIGNATURE时：
| 名称 | 类型 | 描述 |
|---|---|---|
| name | String | device的name |
| createTs | Long | 创建时间戳 |
| authType | String | 认证的类型 |
| secretKey | String | 生成的SK |
| tags | Map<String, String> | 设备的标签 |
authType为CERTIFICATE时：
| 名称 | 类型 | 描述 |
|---|---|---|
| name | String | device的name |
| createTs | Long | 创建时间戳 |
| authType | String | 认证的类型 |
| privateKey | String | 私钥 |
| clientCert | String | 证书内容 |
| tags | Map<String, String> | 设备的标签 |
其他
http-code: 400 配额耗尽(code:QuotaExhausted) 创建的设备数达到上限
示例
请求
Plain Text
1{
2 "name" : "test1",
3 "desc" : "q",
4 "templateId" : "3837fa08-16dd-4c0d-9bb5-dc666d50d3d8",
5 "authType" : "SIGNATURE",
6 "tags": {
7 "abc": "ddd"
8 }
9}返回
Plain Text
1{
2 "name":"test1",
3 "desc":"q",
4 "createTs":1583910343986,
5 "authType":"SIGNATURE",
6 "secretKey":"hybKqPmfsYwWvCRj",
7 "tags": {
8 "abc": "ddd"
9 }
10}删除设备
接口描述
用于设备的删除操作。
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/device/{deviceName} | DELETE |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的id |
| deviceName | String | 否 | URLPath | - | 设备的name |
输出
http-code： 200 （删除当前iotCore中不存在的设备，也会返回200）
示例
请求
Plain Text
1DELETE http://iot.baidubce.com/v1/iotcore/${iotCoreId}/device/${deviceName}返回
Plain Text
1200获取设备列表
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/device/scroll/list | GET |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的Id。 |
| pageSize | Integer | 是 | QueryParam | 20 | 单页获取数目 (pageSize >= 10 && pageSize <= 200) |
| createTimeBefore | Timestamp | 是 | QueryParam | 当前的unix时间戳（ms） | 返回createTime在createTimeBefore之前的pageSize个设备（>=0 并小于当前时间的时间戳 |
| name | String | 否 | QueryParam | "" | 前缀过滤关键字，默认为空，即不过滤。根据name过滤。 |
输出
http-code： 200
| 名称 | 类型 | 描述 |
|---|---|---|
| total | Integer | iotcore下device的总数 |
| pageSize | Integer | 当前请求的数量 |
| createTimeBefore | Timestamp | 当前使用的createTimeBefore |
| data | List<ListDeviceBean> | 请求返回的数据列表 |
ListDeviceBean
| 名称 | 类型 | 描述 |
|---|---|---|
| name | String | 设备名字 |
| desc | String | device的描述信息 |
| createTs | Long | 设备创建的时间戳 |
| updateTs | Long | 设备更新的时间戳 |
| authType | String | 认证的类型 |
| templateId | String | 绑定的templateId |
| tags | Map<String, String> | 设备标签 |
示例
请求
Plain Text
1GET http://iot.baidubce.com/v1/iotcore/atmgmqz/device/scroll/list?createTimeBefore=1591259994883&name=ddd&pageSize=20返回
Plain Text
1{
2 "data":[
3 {
4 "name":"ddd",
5 "desc":"",
6 "createTs":1591119293288,
7 "updateTs":1591119293288,
8 "authType":"SIGNATURE",
9 "templateId":"t3gy95w0",
10 "tags": {
11 "abc": "ddd"
12 }
13 }],
14 "total":2,
15 "pageSize":20,
16 "createTimeBefore":1591259994883
17}查询设备
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/device/{deviceName} | GET |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的id |
| deviceName | String | 否 | URLPath | - | 设备的name |
输出
http-code： 200
| 名称 | 类型 | 描述 |
|---|---|---|
| name | String | 设备名字 |
| desc | String | device的描述信息 |
| createTs | Long | 设备创建的时间戳 |
| updateTs | Long | 更新的时间戳 |
| authType | String | 认证的类型 |
| templateId | String | 绑定的templateId |
| tags | Map<String, String> | 设备标签 |
示例
请求
Plain Text
1GET http://iot.baidubce.com/v1/iotcore/atmgmqz/device/ddd返回
Plain Text
1{
2 "name":"ddd",
3 "desc":"",
4 "createTs":1591119293288,
5 "updateTs":1591119293288,
6 "authType":"SIGNATURE",
7 "templateId":"t3gy95w0",
8 "tags": {
9 "abc": "ddd"
10 }
11}更新设备信息
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/device/{deviceName} | PUT |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的id |
| deviceName | String | 否 | URLPath | - | 设备的name |
| desc | String | 是 | JsonBody | - | 设备描述信息。限制同“创建设备” request中不包含该字段或该字段为null表示不更新。 空字符串表示清空描述信息。 |
| tags | Map<String, String> | 是 | JsonBody | - | 设备标签信息。限制同“创建设备”。request中不包含该字段或该字段为null表示不更新。空map表示清空标签信息。 |
输出
http-code： 200
| 名称 | 类型 | 描述 |
|---|---|---|
| name | String | 设备名字 |
| desc | String | device的描述信息 |
| tags | Map<String, String> | 设备标签 |
示例
请求
Plain Text
1PUT http://iot.baidubce.com/v1/iotcore/atmgmqz/device/ddd
2{
3 "name" : "test1",
4 "desc" : "q",
5 "tags": {
6 "abc": "ddd"
7 }
8}返回
Plain Text
1{
2 "name":"ddd",
3 "desc":"q",
4 "createTs":1591119293288,
5 "updateTs":1591119293288,
6 "authType":"SIGNATURE",
7 "templateId":"t3gy95w0",
8 "tags": {
9 "abc": "ddd"
10 }
11}模板管理
创建设备模板
每个deviceTemplate中会默认添加 events和msg两个topic.
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/template | POST |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的Id，全局唯一。 |
| name | String | 是 | JsonBody | "" | 模板名称。3~40字符，可为汉字、大小写英文、数字、中线、下划线及括号，不可使用其他特殊字符。 |
输出
http-code： 200
| 名称 | 类型 | 描述 |
|---|---|---|
| id | String | 模板Id |
| name | String | 模版名字 |
| createTs | Long | 模板创建的时间戳 |
其他
http-code: 400 配额耗尽(code:QuotaExhausted) 创建的模板数达到上限
示例
请求
Plain Text
1POST http://iot.baidubce.com/v1/iotcore/atmgmqz/template
2{
3 "name" : "general"
4}返回
Plain Text
1{
2 "id":"t8lcbhd3",
3 "name":"general",
4 "createTs":1592393338701
5}获取设备模板
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/template/{templateId} | GET |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的Id，全局唯一。 |
| templateId | String | 否 | URLPath | - | DeviceTemplate的id，全局唯一。 |
输出
http-code： 200
| 名称 | 类型 | 描述 |
|---|---|---|
| templateId | String | 模板Id |
| name | String | 设备名字 |
| createTs | Long | 模板创建的时间戳 |
| updateTs | Long | 模版更新但时间戳 |
| policies | List<GetPolicyResponse> | 策略列表 |
GetPolicyResponse
| 名称 | 类型 | 描述 |
|---|---|---|
| id | String | topic Id |
| topicFilter | String | topic 主题 |
| desc | String | 主题的描述 |
| type | String | SYSTEM / CUSTOM.（SYSTEM）主题无法删除 |
| permission | String | 该主题的权限。 PUB / SUB / ALL / NONE |
| createTs | Long | 模板创建的时间戳 |
示例
请求
Plain Text
1GET http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t8lcbhd3返回
Plain Text
1{
2 "templateId":"t8lcbhd3",
3 "name":"general",
4 "createTs":1592393338701,
5 "updateTs":1592393338739,
6 "policies":[
7 {
8 "id":"0e969bd6-dd69-45ff-abf7-005d270efed6",
9 "topicFilter":"$iot/&{$name}/events",
10 "desc":"客户端向云端发送消息",
11 "type":"SYSTEM",
12 "permission":"PUB",
13 "createTs":1592393338721,
14 "updateTs":1592393338721
15 },
16 {
17 "id":"f70d6548-60a7-4b5d-92cd-d99aef927b03",
18 "topicFilter":"$iot/&{$name}/msg",
19 "desc":"云端向客户端发送消息",
20 "type":"SYSTEM",
21 "permission":"SUB",
22 "createTs":1592393338739,
23 "updateTs":1592393338739
24 }]
25}删除模板
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/template/{templateId} | DELETE |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的Id，全局唯一 |
| templateId | String | 否 | URLPath | - | DeviceTemplate的id，全局唯一 |
输出
http-code：204
示例
请求
Plain Text
1DELETE http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t8lcbhd3返回
Plain Text
1204添加策略
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/template/{templateId}/policy | POST |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的Id，全局唯一 |
| templateId | String | 否 | URLPath | - | DeviceTemplate的id，全局唯一 |
| topicFilter | String | 否 | JsonBody | - | 策略主题名 |
| desc | String | 是 | JsonBody | 空 | 策略描述。0 -128字符 |
| permission | String | 否 | JsonBody | - | 策略中主题对应的权限。PUB,SUB,ALL,NONE |
输出
http-code:201
| 名称 | 类型 | 描述 |
|---|---|---|
| policyId | String | 新添加的主题的Id |
| createTs | Long | 主题的创建时间戳 |
其他
http-code: 400 配额耗尽(code:QuotaExhausted) 创建的设策略数达到上限
示例
请求
Plain Text
1POST http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t1k86ps0/policy
2{
3 "topicFilter" : "#",
4 "desc" : "",
5 "permission" : "ALL"
6}返回
Plain Text
1{
2 "policyId":"c7163706-c9ef-46d4-9c21-c21e5e41ad48",
3 "createTs":1592393999900
4}删除策略
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/template/{templateId}/policy/{policyId} | DELETE |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的Id，全局唯一 |
| templateId | String | 否 | URLPath | - | DeviceTemplate的id，全局唯一 |
| policyId | String | 否 | URLPath | - | Policy的id。全局唯一 |
输出
http-code: 204
示例
请求
Plain Text
1DELETE http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t1k86ps0/policy/c7163706-c9ef-46d4-9c21-c21e5e41ad48返回
Plain Text
1204分页获取模板列表
接口描述
| 相对URL | HttpMethod |
|---|---|
| /v1/iotcore/{iotCoreId}/template/list | GET |
输入
| 名称 | 类型 | 是否可选 | 参数位置 | 默认值 | 描述 |
|---|---|---|---|---|---|
| iotCoreId | String | 否 | URLPath | - | IotCore的Id，全局唯一 |
| pageNo | Integer | 是 | URLParam | 1 | 分页获取的页数。(pageNo >= 1) |
| pageSize | Integer | 是 | URLParam | 20 | 单页获取数目。(pageSize >= 10 && pageSize <= 200) |
| order | String | 是 | URLParam | ASC | 升序还是降序 |
| orderBy | String | 是 | URLParam | createTime | 按什么属性排序。目前仅仅支持createTime |
输出
http-code: 200
| 名称 | 类型 | 描述 |
|---|---|---|
| total | Integer | 指定core下的deviceTemplate的总数 |
| pageNo | Integer | 当前请求的页数 |
| pageSize | Integer | 当前请求的数量 |
| order | String | 升序 / 降序排列 |
| orderBy | String | 排序的属性 |
| data | List<GetDeviceTemplateResponse> | 请求返回的数据列表。 |
GetDeviceTemplateResponse
| 名称 | 类型 | 描述 |
|---|---|---|
| templateId | String | template的Id |
| name | String | template的name |
| createTs | Long | 创建时间戳 |
| policies | List<GetPolicyResponse> | 策略列表。（见上） |
示例
请求
Plain Text
1GET http://iot.baidubce.com/v1/iotcore/atmgmqz/template/list返回
Plain Text
1"data":[
2 {
3 "templateId":"t1k86ps0",
4 "name":"general",
5 "createTs":1592393967591,
6 "updateTs":1592394146972,
7 "policies":[
8 {
9 "id":"97a3ed9e-17d9-4862-b92b-66dc30f30de7",
10 "topicFilter":"$iot/&{$name}/events",
11 "desc":"客户端向云端发送消息",
12 "type":"SYSTEM",
13 "permission":"PUB",
14 "createTs":1592393967611,
15 "updateTs":1592393967611
16 },
17 {
18 "id":"34cb3b45-847b-4b97-ac3f-799e00e89d82",
19 "topicFilter":"$iot/&{$name}/msg",
20 "desc":"云端向客户端发送消息",
21 "type":"SYSTEM",
22 "permission":"SUB",
23 "createTs":1592393967632,
24 "updateTs":1592393967632
25 }]
26 }],
27"total":2,
28"pageNo":1,
29"pageSize":20,
30"order":"ASC",
31"orderBy":"createTime"}
异常返回
对于请求异常或者服务器异常，iot-device服务有统一的返回格式。
| 名称 | 类型 | 描述 |
|---|---|---|
| requestId | String | 代表这次请求的id |
| code | String | 异常的类型,每个api可能有不同的类型 |
| message | String | 异常的详细信息 |
http返回码遵循http协议（例如404 not found， 400 bad request）
code每个api可能不同，以下是统一的code：
- http-code: 400 参数错误(code: BadRequest) 任意请求参数不符合规范；
- http-code: 403 禁止访问(code:forbidden) 对当前iotCore没有访问权限；
- http-code: 500 内部出错(code:INTERNAL_SERVER_ERROR)，此状态时客户端须重试。
示例
请求
Plain Text
1POST http://iot.baidubce.com/v1/iotcore/atmgmqz/device/new
2
3{
4 "name" : "illegal**",
5 "desc" : "测试使用",
6 "templateId" : "t1k86ps0",
7 "authType" : "SIGNATURE"
8}返回
Plain Text
1{
2 "requestId":"60ea5d26-2fe3-4841-8541-5a67eae683ea",
3 "code":"BadRequest",
4 "message":"Unrecognized characters is not allowed ."
5}| 方法 | API | 说明 |
|---|---|---|
| POST | /v1/iotcore/{iotCoreId}/device/new | 创建单个设备 |
请求参数
| 参数名称 | 参数类型 | 是否必须 | 说明 |
|---|---|---|---|
| iotCoreId | string | 必选 | URLPath，IoT Core的 id，可在 IoT Core 列表页获取 |
| name | string | 必选 | 设备在此 IoT Core 内的唯一标识，与deviceName、deviceId 同义 |
| templateId | string | 必选 | 设备模板的Id，可在控制台查看 |
| authType | string | 必选 | 认证类型，可选值：SIGNATURE密钥、 CERT证书；默认为SIGNATURE |
| desc | string | 必选 | device 的描述信息0-128任意字符 |
正常返回
HTTP Code：201
authType为SIGNATURE时：
| 名称 | 类型 | 描述 |
|---|---|---|
| name | String | 设备在此 IoT Core 内的唯一标识，与deviceName、deviceId同义 |
| createTs | Long | 创建时间 |
| authType | String | 认证的类型 |
| secretKey | String | 生成的DeviceSecret |
authType为CERTIFICATE时：
| 名称 | 类型 | 描述 |
|---|---|---|
| name | String | 设备在此 IoT Core 内的唯一标识，与deviceName、deviceId同义 |
| createTs | Long | 创建时间 |
| authType | String | 认证的类型 |
| privateKey | String | 私钥 |
| publicKey | String | 公钥 |
| clientCert | String | 证书内容 |
| clientCertCA | String | CA内容 |
异常返回
| 错误码 | code | 描述 |
|---|---|---|
| 400 | BadRequest | 参数错误；任意请求参数不符合规范 |
| 400 | QuotaExhausted | 配额耗尽；创建的设备数达到上限 |
| 403 | forbidden | 禁止访问；对当前iotCore没有访问权限 |
| 500 | INTERNAL_SERVER_ERROR | 内部出错；此状态时客户端可重试 |
请求示例
Plain Text
1POST /v1/iotcore/aweqgsn/device/new HTTP/1.1
2Host: iot.baidubce.com
3Authorization: {authorization}
4Content-Type: application/json; charset=utf-8
5{
6 "name" : "devicetest1",
7 "desc" : "这是一个测试设备",
8 "templateId" : "t3837fa0",
9 "authType" : "SIGNATURE"
10}返回示例
Plain Text
1{
2 "name":"devicetest1",
3 "desc":"这是一个测试设备",
4 "createTs":1583910343986,
5 "authType":"SIGNATURE",
6 "secretKey":"hybKqPmfEYwWvCRj"
7}异常返回示例
Plain Text
1{
2 "requestId": "49eb817c-636d-4de1-b2c2-67a6004742f8",
3 "code": "DeviceNameOccupied",
4 "message": "Device name has been occupied, iotCoreId=aweqgsn, deviceName=test"
5}