设备管理

更新时间：2022-08-26

设备管理

创建设备

接口描述

相对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保留字

"s", "sub", "subject",
"o", "obj", "objective",
"e", "env", "environment",
"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) 创建的设备数达到上限

示例

请求

{
    "name" : "test1",
    "desc" : "q",
    "templateId" : "3837fa08-16dd-4c0d-9bb5-dc666d50d3d8",
    "authType" : "SIGNATURE",
    "tags": {
        "abc": "ddd"
    }
}

{
    "name":"test1",
    "desc":"q",
    "createTs":1583910343986,
    "authType":"SIGNATURE",
    "secretKey":"hybKqPmfsYwWvCRj",
    "tags": {
        "abc": "ddd"
    }
}

删除设备

接口描述

用于设备的删除操作。

相对URL	HttpMethod
/v1/iotcore/{iotCoreId}/device/{deviceName}	DELETE

输入

名称	类型	是否可选	参数位置	默认值	描述
iotCoreId	String	否	URLPath	-	IotCore的id
deviceName	String	否	URLPath	-	设备的name

输出

http-code： 200 （删除当前iotCore中不存在的设备，也会返回200）

示例

请求

DELETE http://iot.baidubce.com/v1/iotcore/${iotCoreId}/device/${deviceName}

接口描述

相对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>	设备标签

示例

请求

GET http://iot.baidubce.com/v1/iotcore/atmgmqz/device/scroll/list?createTimeBefore=1591259994883&name=ddd&pageSize=20

{
    "data":[
        {
            "name":"ddd",
            "desc":"",
            "createTs":1591119293288,
            "updateTs":1591119293288,
            "authType":"SIGNATURE",
            "templateId":"t3gy95w0",
            "tags": {
                "abc": "ddd"
            }
        }],
    "total":2,
    "pageSize":20,
    "createTimeBefore":1591259994883
}

查询设备

接口描述

相对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>	设备标签

示例

请求

GET http://iot.baidubce.com/v1/iotcore/atmgmqz/device/ddd

{
    "name":"ddd",
    "desc":"",
    "createTs":1591119293288,
    "updateTs":1591119293288,
    "authType":"SIGNATURE",
    "templateId":"t3gy95w0",
    "tags": {
       "abc": "ddd"
    }
}

更新设备信息

接口描述

相对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>	设备标签

示例

请求

PUT http://iot.baidubce.com/v1/iotcore/atmgmqz/device/ddd
{
    "name" : "test1",
    "desc" : "q",
    "tags": {
        "abc": "ddd"
    }
}

{
    "name":"ddd",
    "desc":"q",
    "createTs":1591119293288,
    "updateTs":1591119293288,
    "authType":"SIGNATURE",
    "templateId":"t3gy95w0",
    "tags": {
       "abc": "ddd"
    }
}

模板管理

创建设备模板

每个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) 创建的模板数达到上限

示例

请求

POST http://iot.baidubce.com/v1/iotcore/atmgmqz/template
{
    "name" : "general"
}

{
    "id":"t8lcbhd3",
    "name":"general",
    "createTs":1592393338701
}

获取设备模板

接口描述

相对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	模板创建的时间戳

示例

请求

GET http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t8lcbhd3

{
    "templateId":"t8lcbhd3",
    "name":"general",
    "createTs":1592393338701,
    "updateTs":1592393338739,
    "policies":[
        {
            "id":"0e969bd6-dd69-45ff-abf7-005d270efed6",
            "topicFilter":"$iot/&{$name}/events",
            "desc":"客户端向云端发送消息",
            "type":"SYSTEM",
            "permission":"PUB",
            "createTs":1592393338721,
            "updateTs":1592393338721
        },
        {
            "id":"f70d6548-60a7-4b5d-92cd-d99aef927b03",
            "topicFilter":"$iot/&{$name}/msg",
            "desc":"云端向客户端发送消息",
            "type":"SYSTEM",
            "permission":"SUB",
            "createTs":1592393338739,
            "updateTs":1592393338739
        }]
}

删除模板

接口描述

相对URL	HttpMethod
/v1/iotcore/{iotCoreId}/template/{templateId}	DELETE

输入

名称	类型	是否可选	参数位置	默认值	描述
iotCoreId	String	否	URLPath	-	IotCore的Id，全局唯一
templateId	String	否	URLPath	-	DeviceTemplate的id，全局唯一

输出

http-code：204

示例

请求

DELETE http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t8lcbhd3

接口描述

相对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) 创建的设策略数达到上限

示例

请求

POST http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t1k86ps0/policy
{
    "topicFilter" : "#",
    "desc" : "",
    "permission" : "ALL"
}

{
    "policyId":"c7163706-c9ef-46d4-9c21-c21e5e41ad48",
    "createTs":1592393999900
}

删除策略

接口描述

相对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

示例

请求

DELETE http://iot.baidubce.com/v1/iotcore/atmgmqz/template/t1k86ps0/policy/c7163706-c9ef-46d4-9c21-c21e5e41ad48

接口描述

相对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>	策略列表。（见上）

示例

请求

GET http://iot.baidubce.com/v1/iotcore/atmgmqz/template/list

"data":[
    {
        "templateId":"t1k86ps0",
        "name":"general",
        "createTs":1592393967591,
        "updateTs":1592394146972,
        "policies":[
            {
                "id":"97a3ed9e-17d9-4862-b92b-66dc30f30de7",
                "topicFilter":"$iot/&{$name}/events",
                "desc":"客户端向云端发送消息",
                "type":"SYSTEM",
                "permission":"PUB",
                "createTs":1592393967611,
                "updateTs":1592393967611
            },
            {
                "id":"34cb3b45-847b-4b97-ac3f-799e00e89d82",
                "topicFilter":"$iot/&{$name}/msg",
                "desc":"云端向客户端发送消息",
                "type":"SYSTEM",
                "permission":"SUB",
                "createTs":1592393967632,
                "updateTs":1592393967632
            }]
    }],
"total":2,
"pageNo":1,
"pageSize":20,
"order":"ASC",
"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)，此状态时客户端须重试。

示例

请求

POST http://iot.baidubce.com/v1/iotcore/atmgmqz/device/new

{
    "name" : "illegal**",
    "desc" : "测试使用",
    "templateId" : "t1k86ps0",
    "authType" : "SIGNATURE"
}

{
    "requestId":"60ea5d26-2fe3-4841-8541-5a67eae683ea",
    "code":"BadRequest",
    "message":"Unrecognized characters is not allowed ."
}

方法	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	内部出错；此状态时客户端可重试

请求示例

POST /v1/iotcore/aweqgsn/device/new HTTP/1.1
Host: iot.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
{
  "name" : "devicetest1",
  "desc" : "这是一个测试设备",
  "templateId" : "t3837fa0",
  "authType" : "SIGNATURE"
}

返回示例

{
    "name":"devicetest1",
    "desc":"这是一个测试设备",
    "createTs":1583910343986,
    "authType":"SIGNATURE",
    "secretKey":"hybKqPmfEYwWvCRj"
}

异常返回示例

{
    "requestId": "49eb817c-636d-4de1-b2c2-67a6004742f8",
    "code": "DeviceNameOccupied",
    "message": "Device name has been occupied, iotCoreId=aweqgsn, deviceName=test"
}

概述

典型实践

物联网核心套件 IoTCore

设备管理

设备管理

创建设备

接口描述

输入

输出

示例

删除设备

接口描述

输入

输出

示例

获取设备列表

接口描述

输入

输出

示例

查询设备

接口描述

输入

输出

示例

更新设备信息

接口描述

输入

输出

示例

模板管理

创建设备模板

接口描述

输入

输出

示例

获取设备模板

接口描述

输入

输出

示例

删除模板

接口描述

输入

输出

示例

添加策略

接口描述

输入

输出

示例

删除策略

接口描述

输入

输出

示例

分页获取模板列表

接口描述

输入

输出

示例

异常返回

示例