百度智能云物联网核心套件 IoT Core API参考 - 设备管理

物联网核心套件 IoT Core

简介/价格/文档

百度智能云物联网核心套件 IoT Core API参考 - 设备管理

文档简介：

设备管理：创建设备：接口描述：相对URL ：/v1/iotcore/{iotCoreId}/device/new； HttpMethod：POST 输入： iotCoreId，String，否，URLPath iotCoreId，通过管理控制台获取。

*此产品及展示信息均由百度智能云官方提供。免费试用咨询热线：400-826-7010，为您提供专业的售前咨询，让您快速了解云产品，助您轻松上云！微信咨询

免费试用、价格特惠

文档详情

设备管理

创建设备

接口描述

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

相似文档

百度智能云物联网核心套件 IoT Core 实践 - 设备状态数据存储到时序数据库TSDB
简介：本文档介绍如何将设备上报的状态数据通过规则引擎存储到时序数据库TSDB中，应用程序可以从TSDB中查询设备的历史状态数据。阅读本示例前建议先熟悉快速入门文档。
百度智能云物联网核心套件 IoT Core 实践 - 数据转发到百度消息服务BMS
简介：本文档介绍通过规则引擎服务将MQTT消息转发至百度消息服务（BMS），以及相应的操作示例。阅读本示例前建议先熟悉快速入门文档。
百度智能云物联网核心套件 IoT Core 实践 - 数据转发到函数计算服务CFC
一、简介：在本教程中，您将学习到如何将 IoT Core 的设备消息通过「规则引擎」转发至「函数计算 CFC」，并通过「函数计算 CFC」进行用户自定义的数据处理。
百度智能云物联网核心套件 IoT Core 实践 - 数据转发到用户 Kafka
一、简介：在本教程中，您将学习到如何将 IoT Core 的设备消息通过『规则引擎』转发至不同账户下的百度消息服务 BMS 实例，可以实现跨账户消息转发等需求。本文主要包括简介、场景描述、注意事项、操作步骤 4 部分内容，通过具体示例展示了相关使用流程。
百度智能云物联网核心套件 IoT Core 常见问题QA
Q：我的物接入IoT Hub还能使用吗？ A：物接入将于2022年10月31日下线。可参考迁移手册进行迁移：IoT Hub/规则引擎迁移指导手册 Q：物联网核心套件是什么？ A：物联网核心套件IoT Core是提供设备接入、管理、规则引擎、IoT边缘能力的物联网服务集合。服务范围大致相当于原IoT Hub数据型+设备型+规则引擎+边缘计算中物联网部分。

文档中心

全民上云·上云补贴申领

免费试用（限企业）

设备管理

创建设备

接口描述

输入

输出

示例

删除设备

接口描述

输入

输出

示例

获取设备列表

接口描述

输入

输出

示例

查询设备

接口描述

输入

输出

示例

更新设备信息

接口描述

输入

输出

示例

模板管理

创建设备模板

接口描述

输入

输出

示例

获取设备模板

接口描述

输入

输出

示例

删除模板

接口描述

输入

输出

示例

添加策略

接口描述

输入

输出

示例

删除策略

接口描述

输入

输出

示例

分页获取模板列表

接口描述

输入

输出

示例

异常返回

示例