# IoTPaaS应用侧API文档
# 目录
# 0. 修改历史
| 文档版本 | 说明 | 日期 | 修改人 | 涉及改动 |
|---|---|---|---|---|
| v0.1 | 20211230 | 杨明 | 初始版本 | |
| v0.2 | 20220304 | 蔡成浩 | 接口补充 | |
| v0.3 | 20220314 | 蔡成浩 | 描述变更 | |
| v0.4 | 20220323 | 蔡成浩 | MQTT数据订阅 | |
| v0.5 | 20220524 | 蔡成浩 | 物模型说明 | |
| v0.6 | 动参配置、设备标签、产品标签等 | 20220617 | 蔡成浩、谢湘翼 | 接口补充 |
| v0.7 | 名词介绍、项目、空间接口 | 20220729 | 蔡成浩 | 文档接口补充 |
# 1. 关于IoT PaaS
# 1.1 产品简介
IoT PaaS服务于智慧社区、智慧园区、智慧城市等解决方案集成应用，对下通过设备直连、网关连接、第三方平台对接等方式，将海量设备数据采集上云，在云平台对数据进行存储、加工、处理，提供给解决方案进行快速组合封装。
平台是一个开放性的能力服务平台，其核心能力体现在设备接入、数据处理、应用能力和常用功能的标准化封装，支持多种物联网通讯协议：MQTT、HTTP等，支持海量接入终端传感、智能控制器等硬件设备。
# 1.2 方案架构
# 1.3 设备节点类型
节点类型分为：直连设备、网关设备、网关子设备。
直连设备：支持设备按照MQTT或HTTP协议接入到IoT PaaS。
网关设备：网关设备目前只支持MQTT协议接入。
网关子设备：网关子设备不具备直接上云的能力，需要借助网关设备接入到IoT PaaS。
# 1.4 名词解释
| 名词 | 描述 |
|---|---|
| 产品 | 设备的集合，通常指一组具有相同功能的设备。IoT PaaS为每个产品颁发全局唯一的ProductKey。 |
| 设备 | 归属于某个产品下的具体设备。IoT PaaS为设备颁发产品内唯一的标识DeviceNumber。设备可以直接连接IoT PaaS，也可以作为子设备通过网关连接IoT PaaS。 |
| 分组 | IoT PaaS支持建立设备分组，分组中可包含不同产品下的设备。通过设备组来进行跨产品管理设备。 |
| 网关 | 能够直接连接IoT PaaS的设备，且具有子设备管理功能，能够代理子设备连接云端。 |
| 子设备 | 本质上也是设备。子设备不能直接连接IoT PaaS，只能通过网关连接。 |
| 设备证书 | 设备证书指ProductKey、DeviceNumber、DeviceSecret的组合。ProductKey：是IoT PaaS为产品颁发的全局唯一标识。该参数很重要，在设备认证以及通信中都会用到，因此需要您保管好。DeviceNumber：在注册设备时，自定义的或系统生成的设备名称，具备产品维度内的唯一性。该参数很重要，在设备认证以及通信中都会用到，因此需要您保管好。DeviceSecret：IoT PaaS为设备颁发的设备密钥，和DeviceNumber成对出现。该参数很重要，在设备认证时会用到，因此需要您保管好并且不能泄露。 |
| ProductSecret | 由IoT PaaS颁发的产品密钥，通常与ProductKey成对出现，可用于一型一密的认证方案。该参数很重要，需要您保管好，不能泄露。 |
| 标签 | 标签分为产品标签、设备标签。产品标签：描述同一个产品下，所有设备所具有的共性信息。设备标签：通常根据设备的特性为设备添加的特有标记，您可以自定义标签内容。 |
| Vlink协议 | IoT PaaS定义的设备与云端之间的通信协议。 |
| 物模型 | 是对设备在云端的功能描述，包括设备的属性、服务和事件。IoT PaaS通过定义一种物的描述语言来描述物模型，称之为TSL（即 Thing Specification Language），采用JSON格式，您可以根据TSL组装上报设备的数据。 |
| 属性 | 设备的功能模型之一，一般用于描述设备运行时的状态，如环境监测设备所读取的当前环境温度等。属性支持GET和SET请求方式。应用系统可发起对属性的读取和设置请求。 |
| 期望属性值 | 通过期望属性值功能，设置您希望的设备属性值。若设备在线，将实时更新属性值；若设备离线，期望属性值将缓存在云端。设备上线后，获取期望属性值，并更新属性值。 |
| 服务 | 设备的功能模型之一，设备可被外部调用的能力或方法，可设置输入参数和输出参数。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，如执行某项特定的任务。 |
| 事件 | 设备的功能模型之一，设备运行时的事件。事件一般包含需要被外部感知和处理的通知信息，可包含多个输出参数。例如，某项任务完成的信息，或者设备发生故障或告警时的温度等，事件可以被订阅和推送。 |
| 设备影子 | 是一个JSON文档，用于存储设备或者应用的当前状态信息。每个设备都会在云端有唯一的设备影子。无论该设备是否连接到Internet，您都可以使用设备影子通过MQTT协议或HTTP协议获取和设置设备的状态。 |
| 规则引擎 | 通过创建、配置规则，以实现服务端订阅、数据流转和场景联动。 |
| 服务端订阅 | 服务端订阅产品下所有类型的消息： 设备上报消息、设备状态变化通知、设备生命周期变更、物模型生命周期变更、设备影子变更通知。目前支持两种方式实现服务端订阅：AMQP：高级消息队列协议。服务端通过AMQP协议接入云端，接收云端推送的消息。MQTT：将消息流转到指定MQTT Broker中，您的服务端从对应TOPIC主题中接收消息。 |
| 场景联动 | 场景联动是一种开发自动化业务逻辑的可视化编程方式。您可以通过可视化的方式定义设备之间联动规则，并将规则部署至云端或者边缘端。 |
| 一机一密 | 每个设备烧录其唯一的设备证书（ProductKey、DeviceNumber和DeviceSecret）。当设备与IoT PaaS建立连接时，IoT PaaS对其携带的设备证书信息进行认证。 |
| 一型一密 | 同一产品下所有设备可以烧录相同产品证书（即ProductKey和ProductSecret）。设备发送激活请求时，IoT PaaS对其携带的产品证书信息进行认证，认证通过，下发该设备接入所需的信息。设备再携带这些信息与IoT PaaS建立连接。 |
# 2. 配置物模型
# 2.1 物模型概述
# 2.1.1 什么是物模型
物模型是平台为产品定义的数据模型，用于描述产品的功能。
# 2.1.2 功能说明
物模型是物理空间中的实体（如传感器、车载装置、楼宇、工厂等）在云端的数字化表示，从属性、服务和事件三个维度，分别描述了该实体是什么、能做什么、可以对外提供哪些信息。定义了物模型的这三个维度，即完成了产品功能的定义。
| 功能类型 | 说明 |
|---|---|
| 属性（Property） | 用于描述设备运行时具体信息和状态。 例如，环境监测设备所读取的当前环境温度、智能灯开关状态、电风扇风力等级等。 属性可分为读写和只读两种类型，即支持读取和设置属性。 |
| 服务（Service） | 指设备可供外部调用的指令或方法。服务调用中可设置输入和输出参数。输入参数是服务执行时的参数，输出参数是服务执行后的结果。 相比于属性，服务可通过一条指令实现更复杂的业务逻辑，例如执行某项特定的任务。 服务分为异步和同步两种调用方式。 |
| 事件（Event） | 设备运行时，主动上报给云端的信息，一般包含需要被外部感知和处理的信息、告警和故障。事件中可包含多个输出参数。 例如，某项任务完成后的通知信息；设备发生故障时的温度、时间信息；设备告警时的运行状态等。 事件可以被订阅和推送。 |
# 2.1.3 使用说明
平台通过定义一种物的描述语言来描述物模型模块和功能，称为TSL（Thing Specification Language）。
物模型TSL文件格式为JSON。您可在平台产品详情页面，单击功能定义页签，单击物模型TSL，查看或导出JSON格式的TSL。相关字段说明，请参见物模型TSL字段说明。
# 2.2TSL 概述
# 2.2.1 物模型TSL字段说明
本文介绍物模型TSL文件中JSON字段及其详细说明。
说明 为了完整展示TSL的结构，以下示例中包含所有参数，不代表实际使用中可能出现的组合。参数后的文字为参数说明，非参数值。各参数的使用场景，请参见参数说明。
{
"profile": {
"productKey": "当前产品的ProductKey",
"version": "版本号",
"productKey":"当前产品的ProductKey",
"productName":"当前产品的名称",
"authType": "秘钥类型 1：一机一密 2：一型一密",
"modelCode":"型号编码",
"cateCode":"品类编码",
"protocolType":"协议类型 5：modbus"
},
"properties": [
{
"identifier": "属性唯一标识符（产品下唯一）",
"name": "属性名称",
"accessMode": "属性读写类型：只读（r）或读写（rw）。",
"required": "是否是标准功能的必选属性 0非必填，1必填",
"dataType": {
"type": "属性类型: int32（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的值方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
"specs": {
"min": "参数最小值（int、float、double类型特有）",
"max": "参数最大值（int、float、double类型特有）",
"unit": "属性单位（int、float、double类型特有，非必填）",
"unitName": "单位名称（int、float、double类型特有，非必填）",
"size": "数组元素的个数，最大512（array类型特有）。",
"step": "步长（text、enum类型无此参数）",
"length": "数据长度，最大10240（text类型特有）。",
"0": "0的值（bool类型特有）",
"1": "1的值（bool类型特有）",
"item": {
"type": "数组元素的类型（array类型特有）"
}
}
}
}
],
"events": [
{
"identifier": "事件唯一标识符（产品下唯一，其中post是默认生成的属性上报事件。）",
"name": "事件名称",
"desc": "事件描述",
"eventType": "事件类型 1信息，2告警，3故障",
"required": "是否是标准功能的必选事件",
"outputData": [
{
"identifier":"出参唯一标识符",
"name":"出参名称",
"type":"属性类型: int32（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
"specs":{
"0":"0的值（bool类型特有）",
"1":"1的值（bool类型特有）",
"min":"参数最小值（int、float、double类型特有）",
"max":"参数最大值（int、float、double类型特有）",
"unit":"属性单位（int、float、double类型特有，非必填）",
"unitName":"单位名称（int、float、double类型特有，非必填）",
"size":"数组元素的个数，最大512（array类型特有）。",
"step":"步长（text、enum类型无此参数）",
"length":"数据长度，最大10240（text类型特有）。",
"item":{
"type":"数组元素的类型（array类型特有）"
}
}
}
],
"method": "事件对应的方法名称（根据identifier生成）"
}
],
"services": [
{
"identifier": "服务唯一标识符",
"name": "服务名称",
"desc": "服务描述",
"required": "是否是标准功能的必选服务",
"callType": "1（同步调用）或2（异步调用）",
"inputData": [
{
"identifier":"出参唯一标识符",
"name":"出参名称",
"type":"属性类型: int32（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
"specs":{
"0":"0的值（bool类型特有）",
"1":"1的值（bool类型特有）",
"min":"参数最小值（int、float、double类型特有）",
"max":"参数最大值（int、float、double类型特有）",
"unit":"属性单位（int、float、double类型特有，非必填）",
"unitName":"单位名称（int、float、double类型特有，非必填）",
"size":"数组元素的个数，最大512（array类型特有）。",
"step":"步长（text、enum类型无此参数）",
"length":"数据长度，最大10240（text类型特有）。",
"item":{
"type":"数组元素的类型（array类型特有）"
}
}
}
],
"outputData": [
{
"identifier":"出参唯一标识符",
"name":"出参名称",
"type":"属性类型: int32（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
"specs":{
"0":"0的值（bool类型特有）",
"1":"1的值（bool类型特有）",
"min":"参数最小值（int、float、double类型特有）",
"max":"参数最大值（int、float、double类型特有）",
"unit":"属性单位（int、float、double类型特有，非必填）",
"unitName":"单位名称（int、float、double类型特有，非必填）",
"size":"数组元素的个数，最大512（array类型特有）。",
"step":"步长（text、enum类型无此参数）",
"length":"数据长度，最大10240（text类型特有）。",
"item":{
"type":"数组元素的类型（array类型特有）"
}
}
}
],
"method": "服务对应的方法名称（根据identifier生成）"
}
]
}
# 2.2.2 物模型TSL示例
{
"profile":{
"version":"1",
"productKey":"Ysob4TcEyDN",
"productName":"智能门锁a110",
"authType":1,
"modelCode":"yda110",
"cateCode":"ZNMSDEMO",
"protocolType":"1"
},
"properties":[
{
"identifier":"RemainBattery",
"name":"剩余电量",
"dataType":{
"type":"int32",
"specs":{
"min":"0",
"max":"100",
"step":"1"
}
},
"accessMode":"rw",
"required":0,
"desc":"",
"method":"thing.event.property.post",
"elementType":1,
"extDesc":"",
"isStandard":0
}
],
"events":[
{
"identifier":"DoorOpenNotification",
"name":"开门通知",
"required":0,
"desc":"",
"method":"thing.event.DoorOpenNotification.post",
"elementType":2,
"eventType":1,
"outputData":[
{
"identifier":"LockType",
"name":"开锁方式",
"type":"enum",
"specs":{
"0":"指纹",
"1":"密码",
"2":"卡",
"3":"机械钥匙"
}
},
{
"identifier":"KeyId",
"name":"钥匙ID",
"type":"text",
"specs":{
"length":"256"
}
}
],
"extDesc":"",
"isStandard":0
}
],
"services":[
{
"identifier":"AddKey",
"name":"添加钥匙",
"required":0,
"desc":"",
"method":"thing.service.AddKey",
"callType":2,
"elementType":3,
"outputData":[
{
"identifier":"KeyId",
"name":"钥匙ID",
"type":"text",
"specs":{
"length":"256"
}
}
],
"inputData":[
{
"identifier":"LockType",
"name":"开锁方式",
"type":"enum",
"specs":{
"0":"指纹",
"1":"密码",
"2":"卡",
"3":"机械钥匙"
}
},
{
"identifier":"UserLimit",
"name":"用户权限",
"type":"enum",
"specs":{
"1":"普通用户",
"2":"管理员"
}
}
],
"extDesc":"",
"isStandard":0
}
]
}
# 2.3 物模型支持的数据类型
平台支持以下数据类型，为产品定义物模型功能时，您可选择使用。
| 数据类型 | 说明 | 示例 |
|---|---|---|
| int32 | 32位整型。 | 10 |
| float | 单精度浮点型。 | 1.1 |
| double | 双精度浮点型。 | 1.23 |
| text | 字符串，对应的数据长度不能超过10240字节。 | "Hello world!" |
| date | 时间戳。格式为String类型的UTC时间戳，单位：毫秒。 | "1635839462000" |
| bool | 布尔型。采用0（false）或1（true）来定义布尔值，且0和1为int32类型。 | 0表示关、1表示开。 |
| enum | 枚举型。定义枚举项的参数值和参数描述，参数值必须为整数。 | 整数0表示红色，整数1表示蓝色，整数2表示绿色。 |
| struct | JSON对象。定义一个JSON结构体，结构体内元素类型支持int32、float、double、text、date、bool和enum，不支持结构体嵌套。 | { "name":"Tom", "age":10 } |
| array | 数组。需声明数组内的元素类型、数组元素个数。元素类型支持int32、float、double、text或struct，需确保同一个数组元素类型相同。元素个数限制为1~512个。 | [1, 2, 3, 4, 5, 6] |
| raw | 透传类型。针对复杂数据类型使用透传。 | {"a":{"b":[{"c":"d"}]}} |
# 3. 应用接入流程
# 3.1 凭证申请
向IoT Paas平台产品经理描述需求，申请对应环境的AppKey和AppSecret应用凭证。
管群 B10W00AN10 （18318031850）
潘光勇 B10AAFJ07 （13007438412）
王晓辰 B10W00AB31 （15915337775）
张燕婷 B10AAFI46（18826076411）
# 3.2 对接联调
按照OpenApi的规范调用对应的api进行操作，功能开发。
黄伟东 B10AAFJ131 （18028767598）
# 4. 云端通用开发指南
# 4.1 云端Open Api通用鉴权机制
概述
平台提供云端接口来使用设备能力。向API的服务端地址发送HTTPS/HTTP GET或POST请求，并按照API接口说明，在请求中加入相应请求参数来调用API。平台根据请求的处理情况，返回处理结果。
环境说明
开发环境: https://api-ihw-dev.vanrui.com:1443
测试环境: https://api-eg-stg.smartihw.com:1443
生产环境: https://api-eg.smartihw.com:1443
Open-API_签名机制
平台会对每个接口访问请求的发送者进行身份验证，所以无论使用HTTP还是HTTPS协议提交请求，都需要在请求中包含签名信息。
三方应用调用能力平台，需要通过open-api
对接前的准备工作
需申请对接（向IoT Paas产品经理申请）
提供资料：
三方系统的名称
能够获取的信息：appKey，appSecret
- 需要知道对接环境的服务名和接口地址
访问地址说明
// host,port: 由对接的平台提供对应环境的地址
// service: 按照功能划分的服务名
// api见下方具体的api定义
//完整的apiurl信息
https://[host]:[port]/open/{service}/{api}
请求说明
- API 遵循RESTFUL 风格。
- API 的请求及响应编码统一使用UTF-8。
- 在发送请求时，必须通过JSON 编码与后端交互，请求必须设置http头部如下：
- Content-Type: application/json （例外：表单提交的需要设置成multipart/form-data ）
- Authorization: appKey:sign
- Content-MD5: QTYyOTFEMTc0RTJCM0Y5OEZCNEY2MkFDOTFBNzNFQzE= 😗*如果body部分为空设置成空字符串""
- 字段使用「小写+ 下划线」的方式进行命名。
请求示例
POST /open/device-configuration/iot/devices/registerDevice
Content-Type: application/json
Authorization: appKye123:TM2MWY5Y2N
Date: Sat, 20 Nov 2286 17:46:39 GMT
Content-MD5: QTYyOTFEMTc0RTJCM0Y5OEZCNEY2MkFDOTFBNzNFQzE=
{
"projectCode":"44030049",
"productKey":"sdfwefEwq",
"deviceNumber":"SJIF256120"
}
响应说明
如无特别标注，返回的数据均是标准的json格式
| 字段名 | 类型 | 必填 | 备注 |
|---|---|---|---|
| code | int | 是 | 业务状态码，请参照以下状态码定义列表 |
| msg | string | 是 | 错误说明，当系统成功返回时( code==0 )为"操作成功" |
| data | map | 是 | 返回的具体数据,如果系统返回异常( code!=0 )为空字典 |
响应示例
{
"msg":"操作成功",
"code":0,
"data": {
"did":"6736933959340392448",
"projectCode":"44030049",
"spaceCode":"1020000",
"deviceTypeCode":"MJ1010111",
"productId":35
}
}
# 4.2 JAVA示例代码
//demo
RestTemplate restTemplate = new RestTemplate();
String url = "https://api-ihw-stg.vanrui.com/open/account/xxxxxx";
ObjectMapper objectMapper = new ObjectMapper();
String body = objectMapper.writeValueAsString(ImmutableMap.of("bodyparam1", "bodyparamvalue1"));
Map<String, String> signHeaders = OpenApiClientAuth.getSignHeaders("POST", url, "appKey", "appSecurity", body, "application/json");
final HttpHeaders headers = new HttpHeaders(); signHeaders.forEach(headers::set);
final HttpEntity<String> httpEntity = new HttpEntity<>(body, headers); final ParameterizedTypeReference<ExternalResult<Boolean>> parameterizedTypeReference = new ParameterizedTypeReference<ExternalResult<Boolean>>() {
};
ExternalResult<Boolean> body1 = restTemplate.exchange(url, HttpMethod.POST, httpEntity, parameterizedTypeReference).getBody(); System.out.println(body1);
//OpenApiClientAuth.java
package com.vanrui.ihw.spring.cloud.starter.common.utils;
Import java.nio.charset.StandardCharsets; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter; import java.util.Base64;
import java.util.HashMap; import java.util.Locale; import java.util.Map; import java.util.Optional;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec; import lombok.extern.slf4j.Slf4j;
import org.springframework.util.DigestUtils; import org.springframework.util.StringUtils;
/**
\* @author yangming
*/ @Slf4j
public class OpenApiClientAuth {
public static final String AUTHORIZATION = "Authorization";
public static final String CONTENT_TYPE = "Content-Type";
public static final String CONTENT_MD5 = "Content-MD5";
public static final String DATE = "Date";
public static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter
.ofPattern("EEE, dd MMM yyyy HH:mm:ss zzz", Locale.ENGLISH);
/**
\* @param httpMethod 请求方式GET,POST,PUT。。。
\* @param url http://baidu.com/xxx/xx?aa=11
\* @param appKey 123123
\* @param appSecret sdfdsf
\* @param bodyString 当为GET时传空, POST时传post的body值
\* @param contentType 请求类型
\* @return 返回授权说需要的Header参数
\* @throws Exception
*/
public static Map<String, String> getSignHeaders(final String httpMethod, final String url,
final String appKey, final String appSecret, final String bodyString, final String contentType) throws Exception {
final String pathResource = OpenApiClientAuth.getPathResource(url);
final String contentTypeValue = contentType != null ? contentType :"application/json";
final String dateValue = DATE_TIME_FORMATTER.format(ZonedDateTime.now(ZoneId.of("GMT")));
final String bodyMd5 = Optional.ofNullable(bodyString).map(OpenApiClientAuth::getMd5String)
.orElse("");
final String sign = OpenApiClientAuth.calculateSing(httpMethod, bodyMd5, contentTypeValue, dateValue, pathResource,appSecret);
final String authorizationString = appKey + ":" + sign;
final Map<String, String> authHeaders = new HashMap<>(4);
authHeaders.put(OpenApiClientAuth.DATE, dateValue);
authHeaders.put(OpenApiClientAuth.AUTHORIZATION, authorizationString);
authHeaders.put(OpenApiClientAuth.CONTENT_TYPE, contentTypeValue);
authHeaders.put(OpenApiClientAuth.CONTENT_MD5, bodyMd5);
return authHeaders;
}
protected static String getMd5String(final String bodyString) {
OpenApiClientAuth.log.debug("getBodyMd5 bodyString ={}", bodyString);
return new String(Base64.getEncoder().encode(DigestUtils.md5Digest(bodyString.getBytes(StandardCharsets.UTF_8))));
}
protected static String getPathResource(final String url) {
final String substring = url.substring(url.indexOf("://") + 3);
return substring.substring(substring.indexOf("/"));
}
protected static String calculateSing(final String httpMethodString, final String bodyMd5,
final String contentTypeValue, final String dateValue, final String pathResource,
final String appSecret) throws InvalidKeyException, NoSuchAlgorithmException {
OpenApiClientAuth.log.debug("method = {}", httpMethodString);
OpenApiClientAuth.log.debug("contentTypeValue = {}", contentTypeValue);
OpenApiClientAuth.log.debug("contentMD5Value = {}", bodyMd5);
OpenApiClientAuth.log.debug("dateValue = {}", dateValue);
OpenApiClientAuth.log.debug("pathResource = {}", pathResource);
OpenApiClientAuth.log.debug("appSecret = {}", appSecret);
final String signToString = OpenApiClientAuth.builderStringToSign(httpMethodString, bodyMd5, contentTypeValue,dateValue,pathResource);
OpenApiClientAuth.log.debug("signToString = {}", signToString);
final String base64HashString = HMAC.hmacSha1Encrypt(signToString,appSecret);
OpenApiClientAuth.log.debug("base64HashString = {}", base64HashString);
final String sign = base64HashString.substring(5, 15); OpenApiClientAuth.log.debug("sign = {}", sign);
return sign;
}
protected static String builderStringToSign(final String method, final String contentMd5Value,
final String contentTypeValue, final String dateValue, final String pathResource) {
return method
\+ "\n"
\+ OpenApiClientAuth.handleNullString(contentMd5Value)
\+ "\n"
\+ OpenApiClientAuth.handleNullString(contentTypeValue)
\+ "\n"
\+ OpenApiClientAuth.handleNullString(dateValue)
\+ "\n"
\+ pathResource;
}
protected static String handleNullString(final String str) {
return !StringUtils.hasText(str) ? "" : str;
}
protected static class HMAC {
private HMAC() {}
private static final String KEY_MAC_SHA1 = "HmacSHA1";
public static String hmacSha1Encrypt(final String encryptText, final String encryptKey)
throws NoSuchAlgorithmException, InvalidKeyException {
final byte[] text = encryptText.getBytes(StandardCharsets.UTF_8);
final byte[] keyData = encryptKey.getBytes(StandardCharsets.UTF_8);
final SecretKeySpec secretKey = new SecretKeySpec(keyData,HMAC.KEY_MAC_SHA1);
final Mac mac = Mac.getInstance(secretKey.getAlgorithm());
mac.init(secretKey);
return new String(Base64.getEncoder().encode(mac.doFinal(text)), StandardCharsets.UTF_8);
}
}
}
//ExternalResult.java
import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@JsonInclude(value= JsonInclude.Include.NON_NULL)
public class ExternalResult<T> {
private Boolean success;
private String msg;
private Integer code;
private T data;
public boolean getSuccess() {
if (success != null) {
return success;
}
return code == 0;
}
}
# 4.3 公共参数
本文档介绍平台云端API的公共请求参数和公共返回参数
# 4.4 公共请求参数
公共请求参数是调用每个API时都需要使用的请求参数。
# 4.5 错误码规范
本文档列举调用IoT PaaS平台API出错时，返回的错误信息。入参数据格式错误、超出限定值、入参缺少必需参数等错误修改，请参见具体API文档的请求参数描述。
# 4.5.1 客户端错误码
以 4开头的错误码为客户端相关错误码。
| 错误码 | 描述 |
|---|---|
| 40400 | 请求资源不存在 |
| 40101 | 未登录 |
| 40102 | 未经授权: %s |
| 42900 | 请求过多被限流 |
注：一般属于客户端编码错误没有按照协议要求或限制规范编码。
# 4.5.2 系统错误码
以 5开头的错误码为服务端相关错误码。
| 错误码 | 描述 |
|---|---|
| 500XX | 一般是服务器内部错误通知对应的开发人员 |
注：一般属于IoT PaaS平台内部异常所导致，请联系IoT PaaS平台开发人员进行解决。
# 4.5.3 业务错误码
以 2开头的错误码为业务相关错误码。
| 错误码 | 描述 |
|---|---|
| 21001 | 登录已失效 |
| 21101 | 数据已存在 |
| 21102 | 验证码错误 |
| 21103 | 存在关联数据, 不允许删除 |
| 21104 | 数据不存在 |
| 21105 | 用户名/密码错误 |
| 21106 | 设备未在IoT PaaS授权，请授权后连接 |
| 21107 | 账户已冻结 |
| 21108 | 应用已锁定 |
| 21301 | 失败: %s |
| 21302 | 设备不存在 |
| 21303 | 下游服务异常: %s |
| 21304 | 设备: %s , 不在线 |
| 21305 | 设备响应超时 |
| 21313 | 参数异常：%s |
| 21314 | 资源不存在：%s |
| 21316 | 设备响应失败：%s |
| 21318 | 分发实例异常：%s |
| 21320 | 设备SN编码不支持中文和+ ## / % *&特殊字符 |
| 21340 | 产品异常: %s |
| 21341 | 产品未发布 |
| 21342 | 产品Key 无效 |
| 21344 | 产品不存在 |
| 21315 | 物模型标识符不存在：%s |
| 21320 | 物模型标识符使用异常：%s |
| 21321 | 物模型元素值校验失败：%s |
| 21380 | Excel读取数据异常%s |
| 21381 | Excel一次最多批量导入1000个设备，请调整后重新上传 |
| 21382 | Excel未填写内容 |
| 21383 | Excel标签格式错误 |
| 21391 | 项目编号不存在：%s |
| 21392 | 空间编号不存在：%s |
| 21370 | 应用无权限 |
| 21371 | TOPO结构正在初始化到缓存,请稍后重试 |
| 21372 | TOPO结构查询function异常 |
注：该错误码代表正常的业务错误，一般具有业务处理意义的。客户端可以结合业务需求，选择性识别判断处理。
# 5 云端IOT API
# 5.1 设备管理
请求路径
https://[host]:[port]/open/device-configuration/{api}
# 5.1.1 注册设备
调用该接口在指定产品下注册设备。
接口说明
注册设备指在IoT PaaS产品下添加设备。在指定产品下成功注册设备后，IoT PaaS平台为设备颁发全局唯一的设备ID（dId），用来标识该设备。在进行与设备相关的操作时，您可能需要提供目标设备的dId。您也可以使用ProductKey和DeviceNumber组合来标识一个设备。其中ProductKey是新建产品时平台为产品颁发的产品Key，DeviceNumber是注册设备时由您指定或由系统随机生成的设备名称。dId的优先级高于ProductKey和DeviceNumber组合。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/registerDevice | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| projectCode | String | 否 | 所属项目编号 |
| spaceCode | String | 否 | 所属空间编号 |
| productKey | String | 是 | 产品Key |
| deviceNumber | String | 否 | 设备编码 |
| deviceName | String | 否 | 设备名称 |
| did | String | 否 | 设备DID |
| longitude | Double | 否 | 经度 |
| latitude | Double | 否 | 纬度 |
| deviceSecret | String | 否 | 设备秘钥 |
返回的data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| did | String | 设备DID。平台为该设备颁发的唯一标识符。 |
| productKey | String | 产品Key |
| deviceSecret | String | 设备秘钥 |
| productSecret | String | 产品密钥 |
| modelCode | String | 产品型号编码 |
| deviceTypeCode | String | 设备类型型号 |
| projectCode | String | 项目编号 |
| spaceCode | String | 空间编号 |
| deviceName | String | 设备名称 |
| createTime | Long | 创建时间 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/registerDevice
{
"projectCode":"44030049",
"productKey":"sdfwefEwq",
"deviceNumber":"SJIF256120"
}
返回示例（新增成功）：
{
"msg":"操作成功",
"code":0,
"data": {
"did":"6736933959340392448",
"projectCode":"44030049",
"spaceCode":"1020000",
"deviceTypeCode":"MJ1010111",
"productId":35
}
}
# 5.1.2 查询设备详情
调用该接口查询指定设备的详细信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/queryDeviceDetail | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备DID。平台为该设备颁发的唯一标识符。和ProductKey与DeviceNumber组合是一一对应的关系。如果您同时传入DID和ProductKey与DeviceNumber组合，则以DID为准。 |
| deviceNumber | String | 否 | 设备编码。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| deviceName | String | 设备名称 |
| deviceNumber | String | 设备编码 |
| projectCode | String | 项目编号 |
| projectName | String | 项目名称 |
| did | String | DID |
| productKey | String | 产品Key |
| productSecret | String | 产品秘钥 |
| deviceSecret | String | 设备密钥 |
| productName | String | 产品名称 |
| deviceTypeCode | String | 设备类型编号 |
| deviceTypeName | String | 设备类型名称 |
| spaceCode | String | 空间编号 |
| spaceName | String | 安装位置 |
| createTime | Date | 创建时间 |
| networkStatus | Integer | 在线状态 1：在线 2：离线 |
| inService | Integer | 是否激活 0:已激活 1:未激活 |
| activeTime | Long | 项目安装时间 |
| version | String | 设备版本号 |
| iccid | String | iccid |
| latestMsgTime | Long | 最后一次通讯时间 |
| longitude | Double | 经度 |
| latitude | Double | 纬度 |
| enable | Integer | 启停状态 0:启用 1：停用 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDeviceDetai?did=6905410181719*****
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"deviceName": "UNIT_F00C",
"systemDeviceName": "温度检测仪1135",
"deviceNumber": "7cdfa1b9a2d8",
"createTime": 1646378084000,
"projectCode": "i000000015",
"projectName": "璞玉山",
"spaceCode": null,
"spaceName": null,
"firmwareVersion": "1.0.1",
"productKey": "SKQ9V4B5Q57",
"productSecret": "2Eh12fPv08evquDi",
"productName": "温度检测仪11",
"deviceSecret": "pmyd1hk92fm1gt6r339l8ebfpmx23gkf",
"deviceTypeCode": "VRZNZD189001",
"did": "6905410181719400448",
"networkStatus": 1,
"activeTime": 1646378084000,
"inService": 0,
"protocol": "标准协议",
"version": "1.0.1",
"iccid": null,
"latestMsgTime": 1646381824000,
"longitude":123.3445,
"latitude":22.1548
}
}
# 5.1.3 删除设备
调用该接口删除指定设备。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/deleteDevice | delete |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备DID。平台为该设备颁发的唯一标识符。和ProductKey与DeviceNumber组合是一一对应的关系。如果您同时传入DID和ProductKey与DeviceNumber组合，则以DID为准。 |
| deviceNumber | String | 否 | 设备编码。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/deleteDevice
{
"did":"6736933959340392448"
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.4 批量获取设备在线状态
批量获取设备在线状态
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/batchGetDeviceState | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| List<Object>> | 是 | ||
| did | String | 否 | 设备DID。平台为该设备颁发的唯一标识符。和ProductKey与DeviceNumber组合是一一对应的关系。如果您同时传入DID和ProductKey与DeviceNumber组合，则以DID为准。 |
| deviceNumber | String | 否 | 设备编码。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| did | String | 设备全局唯一id |
| networkStatus | Integer | 在线状态 1：在线 2：离线 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/batchGetDeviceState
[
{
"did":"6736933959340392448"
},
{
"did":"6736933959340392449"
}
]
返回示例：
{
"msg":"操作成功",
"code":0,
"data":[
{
"did":"6736933959340392448",
"networkStatus":1
},
{
"did":"6736933959340392449",
"networkStatus":2
}
]
}
# 5.1.5 批量激活设备
调用该接口批量激活设备（注意： 单个批次激活设备 不能超过100台）。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/batchActDevices | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| List<Object>> | |||
| projectCode | String | 是 | 所属项目编号 |
| spaceCode | String | 否 | 所属空间编号 |
| productKey | String | 是 | 产品Key |
| deviceNumber | String | 是 | 设备编码 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/batchActDevices
[
{
"projectCode":"44030049",
"spaceCode":"1020000",
"productKey":"sdfwefEwq",
"deviceNumber":"SJIF256120"
},
{
"projectCode":"44030049",
"spaceCode":"1020000",
"productKey":"sdfwefEwq",
"deviceNumber":"SJIF256120"
}
]
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.6 批量解除激活设备
调用该接口批量解除激活设备（注意： 单个批次解除激活设备 不能超过100台）。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/batchInActivateDevice | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| List<Object>> | 是 | ||
| productKey | String | 是 | 产品Key |
| deviceNumber | String | 是 | 设备编码 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/batchInActivateDevice
[
{
"productKey":"sdfwefEwq",
"deviceNumber":"SJIF256120"
},
{
"productKey":"sdfwefEwq",
"deviceNumber":"SJIF256120"
}
]
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.7 查询设备的拓扑关系
调用该接口查询指定网关设备的子设备列表。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/v3/devices/getThingTopo | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备DID。平台为该设备颁发的唯一标识符。和ProductKey与DeviceNumber组合是一一对应的关系。如果您同时传入DID和ProductKey与DeviceNumber组合，则以DID为准。 |
| deviceNumber | String | 否 | 设备编码。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| List<Object>> | ||
| did | String | 设备全局唯一id |
| deviceNumber | String | 设备编码 |
| productKey | String | 产品Key |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/v3/devices/getThingTopo?did=6736933959340392448
返回示例：
{
"msg":"操作成功",
"code":0,
"data":[
{
"did":"6736933959340392448",
"deviceNumber":"FHIQW5926",
"productKey":"sdfsdfeHYR01"
}
]
}
# 5.1.8 增加网关设备拓扑关系
调用该接口通知网关设备增加拓扑关系。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/v2/devices/addThingTopo | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| gatewayDid | String | 否 | 网关did 设备的唯一标识符 |
| gatewayDeviceNumber | String | 否 | 网关DeviceNumber 说明:如果传入该参数，需同时传入productKey |
| gatewayProductKey | String | 否 | 网关产品key 说明:如果传入该参数，需同时传入deviceNumber |
| deviceList | List<Object>> | 是 | 子设备集合 |
| did | String | 否 | 子设备did 设备的唯一标识符。 |
| deviceNumber | String | 否 | 子设备DeviceNumber 说明:如果传入该参数，需同时传入productKey |
| productKey | String | 否 | 子设备产品key 说明:如果传入该参数，需同时传入deviceNumber |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/v2/devices/addThingTopo
{
"gatewayDid":"6905398671135748096",
"deviceList":[
"did":"6905360446253969408",
"did":"6905359941876326400"
]
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.9 移除设备的拓扑关系
调用该接口移除网关或子设备的拓扑关系。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/removeThingTopo | put |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/removeThingTopo?did=6736933959340392448
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.10 查询产品的设备列表
查询产品的设备列表。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/queryDevice | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品key |
| projectCode | String | 否 | 项目编号 |
| spaceCode | String | 否 | 产品编码 |
| limit | Integer | 否 | 参数说明：当前获取的条数限制取值范围：1-50的整数，默认值为10，最大获取50条数据。 |
| last | String | 否 | 参数说明：上一次分页查询结果中最后一条设备的Did。为空：则默认从起始位置开始获取规则。否则：从last的后一条数据开始获取分页数据。 |
返回的 data 消息体定义：
| 名称 | 类型 | 是否必填 | 含义 |
|---|---|---|---|
| deviceName | String | 是 | 设备名称 |
| productKey | String | 是 | 产品key |
| deviceNumber | String | 是 | 设备编码 |
| did | String | 是 | DID |
| projectCode | String | 否 | 项目编号 |
| projectName | String | 否 | 项目名称 |
| spaceCode | String | 否 | 空间编号 |
| spaceName | String | 否 | 安装位置 |
| createTime | Date | 是 | 创建时间 |
| networkStatus | Integer | 是 | 在线状态 1：在线 2：离线 |
| version | String | 是 | 设备版本号 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDevice?did=6905326322269036544
返回示例：
{
"msg":"操作成功",
"code":0,
"data":[
{
"deviceName":"万睿摄像头1",
"deviceNumber":"DJIEDN11120",
"did":"6905326322269036544",
"projectCode":"j1010101",
"projectName":"深圳璞悦山",
"spaceCode":"i10101103",
"spaceName":"一期/二栋",
"createTime":1606210222000,
"networkStatus":1,
"version":"1.0"
}
]
}
# 5.1.11 查询条件下的设备列表
查询条件下的设备列表。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/queryDeviceByCondition | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| projectCode | String | 否 | 项目编号 |
| spaceCode | String | 否 | 空间编号 |
| limit | Integer | 否 | 参数说明：当前获取的条数限制取值范围：1-50的整数，默认值为10，最大获取50条数据。 |
| last | String | 否 | 参数说明：上一次分页查询结果中最后一条设备的Did。为空：则默认从起始位置开始获取规则。否则：从last的后一条数据开始获取分页数据。 |
返回的 data 消息体定义：
| 名称 | 类型 | 是否必填 | 含义 |
|---|---|---|---|
| deviceName | String | 是 | 设备名称 |
| productKey | String | 是 | 产品key |
| deviceNumber | String | 是 | 设备编码 |
| did | String | 是 | DID |
| projectCode | String | 否 | 项目编号 |
| projectName | String | 否 | 项目名称 |
| spaceCode | String | 否 | 空间编号 |
| spaceName | String | 否 | 安装位置 |
| createTime | Date | 是 | 创建时间 |
| networkStatus | Integer | 是 | 在线状态 1：在线 2：离线 |
| version | String | 是 | 设备版本号 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDeviceByCondition?projectCode=j1010101
返回示例：
{
"msg":"操作成功",
"code":0,
"data":[
{
"deviceName":"万睿摄像头1",
"deviceNumber":"DJIEDN11120",
"did":"6736933959340392000",
"projectCode":"j1010101",
"projectName":"深圳璞悦山",
"spaceCode":"i10101103",
"spaceName":"一期/二栋",
"createTime":1606210222000,
"networkStatus":1,
"version":"1.0"
}
]
}
# 5.1.12 查询设备的运行状态
获取设备的运行状态
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/v2/devices/getDeviceStatus | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 要调用服务的设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备编号。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| did | String | 设备全局唯一id |
| networkStatus | Integer | 在线状态 1：在线 2：离线 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/getDeviceStatus?did=6736933959340392448
返回示例：
{
"msg":"操作成功",
"code":0,
"data":{
"did":"6736933959340392448",
"networkStatus":1
}
}
# 5.1.13 修改设备
调用该接口修改指定设备。标黄处字段,修改时填入设备当前最新信息.
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/v3/devices/updateDevice | put |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 要调用服务的设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| productKey | String | 否 | 设备编号。说明 如果传入该参数，需同时传入productKey。 |
| deviceNumber | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| deviceName | String | 是 | 设备名称 |
| usageStatus | Integer | 是 | 设备使用状态 0：使用中 1：维修中 2：报废 3：备用 |
| projectCode | String | 是 | 项目编码 当传入null时，则移除设备项目信息。 |
| spaceCode | String | 是 | 安装区域 当传入null时，则移除设备空间信息。 |
| longitude | Double | 是 | 经度 当传入null时，则移除设备经度信息。 |
| latitude | Double | 是 | 纬度 当传入null时，则移除设备经度信息。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/v3/devices/updateDevice
{
"did":"6736933959340392448",
"spaceCode":"s45123001",
"deviceName":"TEST0001",
"usageStatus":0,
"projectCode":"i4121515",
"longitude":"114.043339",
"latitude":"22.553421"
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.14 查询子设备绑定的网关
调用该接口查询子设备绑定的网关。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/getGatewayBySubDevice | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备编码。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| did | String | 设备全局唯一id |
| deviceNumber | String | 设备编码 |
| productKey | String | 产品Key |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/getGatewayBySubDevice?did=6736933959340392448
返回示例：
{
"msg":"操作成功",
"code":0,
"data":{
"did":"6736933959340392448",
"deviceNumber":"FHIQW5926",
"productKey":"sdfsdfeHYR01"
}
}
# 5.1.15 查询设备动态参数
查询设备动态参数
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/queryDeviceDynamicParams | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 要调用服务的设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备编号。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| isMultipart | Integer | 是否为多组动参 0否 1是 |
| dynamicParams | Object/List | 当isMultipart:0 则类型为Object，当isMultipart:1 则类型为List |
| -{identifier} | String | key为动参标识符，value为对应的值 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDeviceDynamicParams?did=6736933959340392448
返回示例：
{
"msg":"操作成功",
"code":0,
"data":{
"isMultipart":0,
"dynamicParams":{
"loopnum":"1",
"network_key":"1"
}
}
}
# 5.1.16 保存设备动态参数
保存更新设备动态参数
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/saveDeviceDynamicParams | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 要调用服务的设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| productKey | String | 否 | 设备编号。说明 如果传入该参数，需同时传入productKey。 |
| deviceNumber | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| dynamicParams | Object/List | 是 | 设备动参列表 |
| -{identifier} | String | 是 | key为动参标识符 |
| -{value} | Object | 是 | value为动参标识符对应的值 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/saveDeviceDynamicParams
{
"did":"6736933959340392448",
"dynamicParams":{
"loopnum":"1",
"network_key":"1"
}
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.17 查询设备标签
查询设备标签
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/queryDeviceTags | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 要调用服务的设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备编号。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| data | List | |
| -tagKey | String | 标签key |
| -tagValue | String | 标签值 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDeviceTags?did=6736933959340392448
返回示例：
{
"msg":"操作成功",
"code":0,
"data":[
{
"tagKey":"loopnum",
"tagValue":"1"
},
{
"tagKey":"network_key",
"tagValue":"DSAF1E51F5115FW"
}
]
}
# 5.1.18 保存设备标签
保存更新设备标签
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/upsertDeviceTags | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 要调用服务的设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| productKey | String | 否 | 设备编号。说明 如果传入该参数，需同时传入productKey。 |
| deviceNumber | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| deviceTags | list | 是 | 设备标签列表 |
| -tagKey | String | 标签Key | |
| -tagValue | String | 标签值 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/upsertDeviceTags
{
"did":"6736933959340392448",
"deviceTags":[
{
"tagKey":"loopnum",
"tagValue": "10"
},
{
"tagKey":"network_key",
"tagValue": "DSAF1E51F5115FW"
}
]
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.19 删除设备标签
删除设备标签
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/deleteDeviceTags | delete |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备编码。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| tagKeys | List<String>> | 是 | 要删除的设备标签 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| did | String | 设备全局唯一id |
| deviceNumber | String | 设备编码 |
| productKey | String | 产品Key |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/deleteDeviceTags
{
"did":"6736933959340392448",
"tagKeys":[
"loopnum","network_key"
]
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.1.20 根据标签查询设备
根据标签查询设备
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/queryDeviceByTags | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| pageNum | Integer | 是 | 当前页数 |
| pageSize | Integer | 是 | 每页显示多少条 最大100 |
| deviceTags | list | 是 | 设备动参列表 |
| -tagKey | String | 动参标识符 | |
| -tagValue | String | 动参值 |
返回数据
| 名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| -pageNum | Integer | 当前页 | |
| -pageSize | Integer | 每页条数 | |
| -totalPages | Integer | 总页数 | |
| -total | Long | 总条数 | |
| -list | List<Object>> | ||
| deviceName | String | 是 | 设备名称 |
| productKey | String | 是 | 产品key |
| deviceNumber | String | 是 | 设备编码 |
| did | String | 是 | DID |
| projectCode | String | 否 | 项目编号 |
| projectName | String | 否 | 项目名称 |
| spaceCode | String | 否 | 空间编号 |
| spaceName | String | 否 | 安装位置 |
| createTime | Date | 是 | 创建时间 |
| networkStatus | Integer | 是 | 在线状态 1：在线 2：离线 |
| version | String | 是 | 设备版本号 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDeviceByTags
{
"pageNum":1,
"pageSize":10,
"deviceTags":[
{
"tagKey":"loopnum",
"tagValue": "10"
},
{
"tagKey":"network_key",
"tagValue": "DSAF1E51F5115FW"
}
]
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"pageNum": 1,
"pageSize": 10,
"totalPages": 1,
"total": 1,
"list": [
{
"deviceName":"万睿摄像头1",
"deviceNumber":"DJIEDN11120",
"did":"6736933959340392000",
"projectCode":"j1010101",
"projectName":"深圳璞悦山",
"spaceCode":"i10101103",
"spaceName":"一期/二栋",
"createTime":1606210222000,
"networkStatus":1,
"version":"1.0"
}
]
}
}
# 5.1.21 根据标签统计设备
根据标签查询设备
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/querySummaryByTags | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| projectCode | String | 否 | 项目编码 |
| deviceTags | list | 是 | 设备动参列表 |
| -tagKey | String | 动参标识符 | |
| -tagValue | String | 动参值 |
返回数据
| 名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| deviceActive | Integer | 1 | 激活设备数量。 |
| deviceCount | Integer | 10 | 设备总数。 |
| deviceOnline | Integer | 0 | 在线设备数量。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/querySummaryByTags
{
"deviceTags":[
{
"tagKey":"loopnum",
"tagValue": "10"
},
{
"tagKey":"network_key",
"tagValue": "DSAF1E51F5115FW"
}
]
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":{
"deviceActive":1,
"deviceCount":10,
"deviceOnline":2
}
}
# 5.2 产品管理
请求路径
https://[host]:[port]/open/device-configuration/{api}
# 5.2.1 查询产品详情
调用该接口查询指定产品的详情信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/queryProduct | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 否 | 产品key |
| modelCode | String | 否 | 产品型号编码 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| name | String | 名称 |
| nodeType | String | 节点类型: 0直连设备 1网关子设备 2网关设备 |
| networkMode | String | 联网方式 0:以太网 1:2G/3G/4G 2:LoRaWAN 3:NB 4:网关子设备 5:Modbus 6:CPC UA 7:Zigbee 8:BLE 9:其他. |
| status | Integer | 发布状态：0未发布 1已发布. |
| productKey | String | 产品key |
| productSecret | String | 产品密钥 |
| authType | Integer | 认证方式 1: 一机一密 2:一型一密 |
| selfRegistration | Integer | 自动注册 0:关 1:开 |
| isStandard | Integer | 是否为标准品. 0 否 1是 |
| cateCode | String | 品类code |
| cateName | String | 品类名称 |
| modelName | String | 产品型号 |
| modelCode | String | 产品型号编码 |
| protocolCode | Integer | 协议code |
| protocolName | String | 协议名称 |
| reportingCycle | Integer | 数据判断周期 |
| supplier | String | 厂家 |
| brand | String | 品牌 |
| createTime | Long | 创建时间 |
| updateTime | Long | 修改时间 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/queryProduct?productKey=tDQvBJqbUyHs***
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"name": "fdd",
"nodeType": "0",
"networkMode": "0",
"status": 1,
"productKey": "tDQvBJqbUyHs",
"productSecret": "3BXVQqd0MiN2FhvJ",
"authType": 1,
"selfRegistration": 0,
"isStandard": 1,
"cateCode": "11",
"cateName": "随便添加的",
"modelName": "广东佛山孤独颂歌",
"modelCode": "dsfgsdfgdf",
"protocolCode": 1,
"protocolName": "MQTT",
"reportingCycle": 111,
"supplier": "海康",
"brand": "海康",
"createTime":1652695059000,
"updateTime":1652695059000
}
}
# 5.2.2 查询产品列表
调用该接口查询产品列表。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/queryProductList | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| cateCodes | List<String> | 否 | 品类code集合 |
| nodeCode | String | 否 | 品类节点 |
| nodeLevel | Integer | 否 | 品类级别 1: 行业 2:场景 3:品类 |
| isStandard | Integer | 否 | 是否为标准品. 0 否 1是 |
| name | String | 否 | 名称模糊搜索 |
| productTagList | List<TagKeyValueVo> | 否 | 产品标签 |
| status | Integer | 否 | 发布状态：0未发布 1已发布 |
| pageNum | Integer | 是 | 当前页 起始页为1 |
| pageSize | Integer | 是 | 每页条数 最大值为100 |
其中TagKeyValueVo对象属性如下：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| tagKey | String | 是 | 标签key |
| tagValue | String | 否 | 标签value |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| -pageNum | Integer | 当前页 |
| -pageSize | Integer | 每页条数 |
| -totalPages | Integer | 总页数 |
| -total | Long | 总条数 |
| -list | List | 设备列表 |
| productKey | String | 产品key |
| name | String | 名称 |
| status | Integer | 发布状态：0未发布 1已发布 |
| cateCode | String | 品类code |
| cateName | String | 品类名称 |
| modelCode | String | 产品型号编码 |
| modelName | String | 产品型号名称 |
| deviceQty | Integer | 关联设备数 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/queryProductList
{
"cateCodes": [
"gdfwfew"
],
"productTagList": [{
"tagKey": "1",
"tagValue": ""
},{
"tagKey": "1",
"tagValue": "22"
}],
"pageNum": 1,
"pageSize": 10
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"pageNum": 1,
"pageSize": 10,
"totalPages": 1,
"total": 1,
"list": [
{
"productKey": "88xSUsmUuIc",
"name": "cmp水浸",
"status": 1,
"cateCode": "aqws",
"cateName": "aqws",
"modelCode": "ZNZD106007",
"modelName": "CMP水浸传感器RIBA-FSTWI01-WL",
"deviceQty": 3
}
]
}
}
# 5.2.3 添加产品
调用该接口查询分组中的设备列表。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/createProduct | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| name | String | 是 | 产品名称 |
| nodeType | String | 是 | 节点类型: 0直连设备 1网关子设备 2网关设备 |
| networkMode | String | 是 | 联网方式 0,以太网 1,蜂窝(2G/3G/4G/5G) 2,LoRaWAN 5,modbus 6,OPC UA 7,ZigBee 8,BLE 9,其他 10,Wi-Fi 11,OPC DA 12,Bacnet 13,自定义 |
| authType | Integer | 是 | 认证方式， 1 : 一机一密，2：一型一密. |
| isStandard | Integer | 是 | 是否为标准品. 0 否 1是 |
| cateCode | String | 否 | 品类code 当为标准品时,该值必填 |
| modelName | String | 是 | 产品型号名称 |
| modelCode | String | 是 | 产品型号编码 |
| protocolCode | Integer | 是 | 协议code 1,MQTT 2,万睿协议 3,IotHub 4,其他 5,萤石云协议 6,云眸协议 7,智居协议 8,Lora设备 9,Http 10,CMP |
| reportingCycle | Integer | 否 | 数据判断周期 |
| supplier | String | 否 | 厂家 |
| brand | String | 否 | 品牌 |
| desc | String | 否 | 产品描述 |
| productKey | String | 否 | 产品key |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| productKey | String | 产品Key |
| productSecret | String | 产品秘钥 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/createProduct
{
"isStandard":1,
"authType":1,
"name":"测试井盖产品",
"productKey":"",
"cateCode":"ZHCS0106",
"cateName":"井盖监测装置",
"networkMode":"1",
"modelCode":"SJ111",
"modelName":"菲尔斯特SJ111",
"brand":"菲尔斯特",
"supplier":"菲尔斯特",
"reportingCycle":"300",
"nodeType":"0",
"protocolCode":"1",
"desc":"test"
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"productKey": "rPU4PHokGR3",
"productSecret": "IC81m3ryC3k182Pz"
}
}
# 5.2.4 发布/撤销发布产品
调用该接口发布/撤销发布指定产品。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/publishProduct | put |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品key |
| status | Integer | 是 | 发布状态：0撤销发布 1发布 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/publishProduct
{
"productKey":"rPU4PHokGR3",
"status":1
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.2.5 修改产品
调用该接口修改指定产品的信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/updateProduct | put |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品key |
| name | String | 是 | 产品名称 |
| modelName | String | 是 | 产品型号名称 |
| reportingCycle | Integer | 否 | 数据判断周期 |
| supplier | String | 否 | 厂家 |
| brand | String | 否 | 品牌 |
| desc | String | 否 | 产品描述 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/updateProduct
{
"productKey":"rPU4PHokGR3",
"name":"测试井盖产品",
"modelName":"菲尔斯特SJ1111",
"brand":"菲尔斯特",
"supplier":"菲尔斯特",
"reportingCycle":"300",
"nodeType":"0",
"protocolCode":"1",
"desc":"test"
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.2.6 删除产品
调用该接口删除指定产品。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/deleteProduct | delete |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品key |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/deleteProduct
{
"productKey":"rPU4PHokGR3"
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.2.7 保存产品标签
调用该接口创建或者更新产品标签信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/upsertProductTags | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品key |
| tagString | List | 是 | 产品key-value |
| tagKey | String | 是 | 标签key |
| tagValue | String | 是 | 标签value |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/upsertProductTags
{
"productKey": "4bcRb1u0dV6",
"tagString": [{
"tagKey": "3",
"tagValue": "33"
},{
"tagKey": "2",
"tagValue": "44"
}]
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": true
}
# 5.2.8 删除产品标签
调用该接口删除产品标签信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/deleteProductTags | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品key |
| delTagKeyList | List<String> | 是 | 删除产品key列表 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/deleteProductTags
{
"productKey": "4bcRb1u0dV6",
"delTagKeyList": [
"3","2"
]
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": true
}
# 5.2.9 查询产品标签
调用该接口查询产品标签。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/listProductTags | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品key |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/listProductTags?productKey=4bcRb1u0dV6
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": [
{
"tagKey": "1",
"tagValue": "33"
},
{
"tagKey": "2",
"tagValue": "44"
}
]
}
# 5.2.10 查询产品动参配置
调用该接口查询指定产品的详情信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/products/queryDynamicParamsConfig | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 否 | 产品key |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| -data | List | 动参配置列表 |
| paramName | String | 动参名称 |
| identifier | String | 动参标识符 |
| paramType | String | 动参参数类型 "1",int32 "2",double "3",bool "4",enum "5",text "6",float "7",date |
| required | Integer | 是否必须 0非必填 |
| paramDesc | String | 动参描述 |
| updateTime | Long | 动参更新时间 |
| enabled | Integer | 启停状态 0:启用，1：停用 |
| spaces | String | 参数范围 JSON格式 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/products/queryProduct?productKey=tDQvBJqbUyHs***
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":[
{
"paramName":"dsadas",
"identifier":"gfdg",
"paramType":"1",
"required":0,
"paramDesc":null,
"updateTime":1653548948000,
"enabled":0,
"spaces":"{\"min\":\"1\",\"max\":\"3\",\"step\":\"2\",\"unit\":\"n\"}"
},
{
"paramName":"JH",
"identifier":"JGHJ",
"paramType":"2",
"required":0,
"paramDesc":null,
"updateTime":1653549015000,
"enabled":0,
"spaces":"{\"min\":\"1.1\",\"max\":\"2.1\",\"step\":\"1\",\"unit\":\"L\"}"
}
]
}
# 5.3 物模型使用
请求路径
https://[host]:[port]/open/device-configuration/{api}
# 5.3.1 设置设备属性值
调用该接口为指定设备设置属性值。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/thing/setDeviceProperty | post |
返回结果说明
因为云端下发属性设置命令和设备收到并执行该命令是异步的，所以调用该接口时，返回的成功结果只表示云端下发属性设置的请求成功，不能保证设备端收到并执行了该请求。需设备端SDK成功响应云端设置设备属性值的请求，设备属性值才能真正设置成功。
请求参数
| 名称 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
| items | JSON Object | 是 | {"Switch":1,"Color":"blue"} | 要设置的属性信息，数据格式为 JSON Object。属性组成为属性标识符key:属性值value，多个属性用英文逗号隔开。例如，设置智能灯的如下两个属性：标识符为Switch的开关属性，数据类型为Bool，设置值为1（开）；标识符为Color的灯颜色属性，数据类型为String，设置值为blue。那么，Items={"Switch":1,"Color":"blue"}。 |
| did | String | 否 | Q7uOhVRdZRRlDnTLv00100 | 设备DID。平台为该设备颁发的唯一标识符。和ProductKey与DeviceNumber组合是一一对应的关系。如果您同时传入DID和ProductKey与DeviceNumber组合，则以DID为准。 |
| deviceNumber | String | 否 | light | 设备编码。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | a1BwAGV | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
调用API时，除了本文介绍的该API的特有请求参数，还需传入公共请求参数。公共请求参数说明，请参见api签名算法,后续接口不再重复说明
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| code | Int | 错误码 | |
| data | Struct | 调用成功时，返回的数据。 | |
| requestId | String | 平台为该请求生成的唯一标识符。 | |
| messageId | String | 云端向设备下发服务调用的消息ID。 | |
| result | Struct | ||
| msg | String | 错误信息。 | |
| success | Boolean | true | 表示是否调用成功。· true：调用成功。· false：调用失败。 |
示例
参数示例
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/setDeviceProperty
{
"did": "6795983672244699136",
"items": {"switch_1":true}
}
返回示例
{
"success":true,
"msg":"操作成功",
"code":0,
"data":{
"requestId":"Mdo5CsA2FpOf82z9vCg022p31NU5SvE0",
"messageId":"8TGZSr4G4Cd6x5jy",
"result":null
}
}
属性设置相关错误码
| 错误码 | 消息 | 描述 |
|---|---|---|
| 21301 | 失败: [did] 与 [productKey&deviceNumber] 不能同时为空 | 请求参数缺失 |
| 21302 | 设备不存在. | 无法根据参数信息找到设备。 |
| 21304 | 设备: %s , 不在线 | 设备离线，无法设置属性 |
| 21315 | 物模型标识符不存在：%s | 产品下功能定义不存在 |
| 21320 | 物模型标识符使用异常：%s | 该标识符非属性标识符 |
| 21321 | 物模型元素值校验失败：%s | 元素值类型错误 |
| 21305 | 设备响应超时 %s | 设备超时未响应，或设备处理超时 |
| 21351 | 设备处理时,发生错误：%s | 设备处理属性设置失败 |
| 21352 | 设备端繁忙,请稍后再试：%s | 请求过于频繁，设备端繁忙 |
| 21353 | 请求参数错误， 设备入参校验失败：%s | 请求参数错误，设备无法识别 |
| 21316 | 设备响应失败：%s | 设备响应的未知异常 |
# 5.3.2 调用设备服务
调用该接口在一个设备上调用指定服务。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/thing/invokeThingService | post |
请求参数
| 名称 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
| args | JSON Object | 是 | {"param1":1} | 要启用服务的输入入参信息，数据格式为JSON Object，例如args={"param1":1}。若此参数为空时，需传入 args={} 。 |
| identifier | String | 是 | Set | 服务的标识符。设备的服务Identifier，可在控制台中，设备所属的产品的功能定义中查看；或调用QueryThingModel，从返回的物模型信息中查看。 |
| did | String | 否 | 6800675159679172608 | 要调用服务的设备DID，设备的唯一标识符。 |
| deviceNumber | String | 否 | light | 设备编号。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | a1BwAGV | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| msg | String | 错误信息。 | |
| success | Boolean | true | 表示是否调用成功。· true：调用成功。· false：调用失败。 |
| code | Int | 错误码 | |
| data | Struct | 调用成功时，返回的数据。 | |
| requestId | String | 平台为该请求生成的唯一标识符。 | |
| messageId | String | 云端向设备下发服务调用的消息ID。 | |
| result | Object | 同步调用服务，返回的调用结果。异步调用服务，不返回此参数。 | |
| id | String | 消息ID，正常情况下与messageId一致。 | |
| code | Int | 设备回复的状态码 | |
| data | Object | 输出参数 |
示例
请求示例
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/invokeThingService
{
"did":"6800675159679172608",
"identifier":"saveVideo",
"args":{
"channelNo":"1",
"startTime":1621412750000,
"endTime":1621413110000,
"voiceSwitch":2
}
}
同步服务返回
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"requestId": "etD240V1sUI6Z05ycBjDW1j6Nd2H94Q0",
"messageId": "or173pC954Ur3VTo",
"result": {
"url":"fd456ff124.m3u8"
}
}
异步服务返回，设备响应的内容通过服务端订阅推送，见6.1.3.1.3
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"requestId": "etD240V1sUI6Z05ycBjDW1j6Nd2H94Q0",
"messageId": "or173pC954Ur3VTo"
}
}
服务调用相关错误码
| 错误码 | 消息 | 描述 |
|---|---|---|
| 21301 | 失败: [did] 与 [productKey&deviceNumber] 不能同时为空 | 请求参数缺失 |
| 21302 | 设备不存在. | 无法根据参数信息找到设备。 |
| 21304 | 设备: %s , 不在线 | 设备离线，无法下发服务 |
| 21315 | 物模型标识符不存在：%s | 产品下功能定义不存在 |
| 21320 | 物模型标识符使用异常：%s | 该标识符非服务标识符 |
| 21321 | 物模型元素值校验失败：%s | 元素值类型错误 |
| 21305 | 设备响应超时 %s | 设备超时未响应，或设备处理超时 |
| 21351 | 设备处理时,发生错误：%s | 设备处理属性设置失败 |
| 21352 | 设备端繁忙,请稍后再试：%s | 请求过于频繁，设备端处理不过来 |
| 21353 | 请求参数错误， 设备入参校验失败：%s | 请求参数错误，设备无法识别 |
| 21316 | 设备响应失败：%s | 设备响应的未知异常 |
# 5.3.3 查询设备属性快照
调用该接口查询指定设备的属性快照。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/v2/thing/queryDevicePropertyStatus | get |
请求参数
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| did | String | 151515111111 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| propertyStatusInfo | Object | ||
| -identifier | String | Temperture | 属性标识符。 |
| -time | String | 1517553572362 | 属性修改的时间，单位是毫秒。 |
| -value | Object | 25 | 属性值。 |
示例
请求示例
https://api-eg.smartihw.com:1443/open/device-configuration/iot/v2/thing/queryDevicePropertyStatus
{
"did":"6800675159679172608",
}
正常返回示例
{
"msg":"操作成功",
"code":0,
"data":{
"did":"151515111111",
"propertyStatusInfo": [
{
"value": "48",
"time": "1579249151178",
"identifier": "Humidity",
},
{
"value": "32.46",
"time": "1579249151178",
"identifier": "Temperature",
}
]
}
}
# 5.3.4 批量查询设备属性快照
调用该接口批量查询设备的属性快照。
| 相对URI | HTTP 方式 |
|---|---|
| /iot/thing/batchQueryDevicePropertyStatus | post |
请求参数
| 名称 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
| dids | List<String> | 否 | 6800675159679172608 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| did | String | 6800675159679172*** | 设备did |
| propertyStatusInfo | |||
| -identifier | String | Temperture | 属性标识符。 |
| -time | String | 1517553572362 | 属性修改的时间，单位是毫秒。 |
| -value | Object | 25 | 属性值。 |
示例
请求示例
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/batchQueryDevicePropertyStatus
{
"dids":[
"6800675159679172***",
"6736933959340392***"
]
}
正常返回示例
{
"msg":"操作成功",
"code":0,
"data":[
{
"did:":"6800675159679172***",
"propertyStatusInfo":[
{
"value":"48",
"time":"1579249151178",
"identifier":"Humidity"
},
{
"value":"32.46",
"time":"1579249151178",
"identifier":"Temperature"
}
]
}
]
}
# 5.3.5 查询设备影子
调用该接口查询指定设备的影子信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/getDeviceShadow | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
返回的 data 消息体定义：
| 名称 | 类型 | 描述 |
|---|---|---|
| desired | Object | 设备的预期状态。仅当设备影子文档具有预期状态时，才包含desired部分。应用程序向desired部分写入数据，更新事物的状态，而无需直接连接到该设备。 |
| reported | Object | 设备的报告状态。设备可以在reported部分写入数据，报告其最新状态。应用程序可以通过读取该参数值，获取设备的状态。JSON文档中也可以不包含reported部分，没有reported部分的文档同样为有效影子JSON文档。 |
| metadata | Object | 当用户更新设备状态文档后，设备影子服务会自动更新metadata的值。设备状态的元数据的信息包含以 Epoch 时间表示的每个属性的时间戳，用来获取准确的更新时间。 |
| timestamp | Long | 影子文档的最新更新时间。 |
| version | Long | 用户主动更新版本号时，设备影子会检查请求中的version值是否大于当前版本号。如果大于当前版本号，则更新设备影子，并将version值更新到请求的版本中，反之则会拒绝更新设备影子。 该参数更新后，版本号会递增，用于确保正在更新的文档为最新版本。 version参数为long型。为防止参数溢出，您可以手动传入-1将版本号重置为0。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/getDeviceShadow?did=6736933959340392448
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"state": {
"desired": {
"color": "RED",
"sequence": [
"RED",
"GREEN",
"BLUE"
]
},
"reported": {
"color": "GREEN"
}
},
"metadata": {
"desired": {
"color": {
"timestamp": 1650619456994
},
"sequence": {
"timestamp": 1650619456994
}
},
"reported": {
"color": {
"timestamp": 1650619456994
}
}
},
"timestamp": 1650619456994,
"version": 1
}
}
# 5.3.6 修改设备影子
调用该接口修改指定设备的影子信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/v2/devices/updateDeviceShadow | put |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| did | String | 否 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| shadow | Object | 是 | 修改后的设备影子信息。 |
| -method | String | 是 | 取固定值 update |
| -version | Long | 是 | 备影子的版本，必须大于当前影子版本。 |
| -state | Object | 是 | 发送给影子的具体状态 |
| --desired | Object | 是 | 期望的影子状态 |
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/v2/devices/updateDeviceShadow
{
"did":"6741996731459698688",
"shadow":{
"method":"update",
"state":{
"desired":{
"color":"green"
}
},
"version":2
}
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.3.7 查询设备事件上报记录
调用该接口获取设备事件上报记录。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/thing/QueryDeviceEventData | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 示例 | 含义 |
|---|---|---|---|---|
| did | String | 否 | 6800675159679172608 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | light | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | a1BwAGV | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| pageNum | Integer | 是 | 1 | 页数 |
| pageSize | Integer | 是 | 10 | 每页显示的条数 最大为100 |
| isDesc | Boolean | 否 | true | 是否倒序 |
| identifier | String | 否 | TrailingAlarm | 事件标识符 |
| startTime | Long | 否 | 1649299946000 | 开始时间 |
| endTime | Long | 否 | 1649299956000 | 结束时间 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| list | |||
| -name | String | 尾随告警 | 事件名称。 |
| -identifier | String | TrailingAlarm | 事件标识符。 |
| -eventType | String | 1 | 事件类型 1信息 2告警 3故障。 |
| -outputData | String | {"A":"B"} | 事件输出参数 |
| -time | Long | 1649299948000 | 事件采集时间 |
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/queryDeviceEventData?did=6914083768374407168&identifier=TrailingAlarm&pageNum=1&pageSize=10
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"pageNum": 1,
"pageSize": 10,
"totalPages": 1,
"total": 4,
"list": [
{
"name": "尾随告警",
"identifier": "TrailingAlarm",
"eventType": 2,
"outputData": "{\"status\":0}",
"time": 1649299948000
},
{
"name": "尾随告警",
"identifier": "TrailingAlarm",
"eventType": 2,
"outputData": "{\"status\":1}",
"time": 1649299949000
}
]
}
}
# 5.3.8 查询设备事件最新记录
调用该接口获取设备事件的最新记录。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/thing/queryNearestDeviceEvent | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 示例 | 含义 |
|---|---|---|---|---|
| did | String | 否 | 6800675159679172608 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | light | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | a1BwAGV | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/queryNearestDeviceEvent?did=6914083768374407168
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":[
{
"name":"尾随告警",
"identifier":"TrailingAlarm",
"eventType":2,
"outputData":"{\"status\":1}",
"time":1649299949000
},
{
"name":"心跳事件",
"identifier":"heartbeat",
"eventType":1,
"outputData":"{\"appVersion\":\"1.0\",\"version\":\"1.2\",\"simCard\":\"89860446101970351079\"}",
"time":1649299949000
},
{
"name":"玻璃门告警事件",
"identifier":"GlassDoorAlarm",
"eventType":2,
"outputData":"{\"status\":0}",
"time":1649299949000
}
]
}
# 5.3.9 查询设备属性上报记录
调用该接口获取设备属性上报记录。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/thing/queryDevicePropertyData | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 示例 | 含义 |
|---|---|---|---|---|
| did | String | 否 | 6800675159679172608 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | light | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | a1BwAGV | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| pageNum | Integer | 是 | 1 | 页数 |
| pageSize | Integer | 是 | 10 | 每页显示的条数 最大为100 |
| isDesc | Boolean | 否 | true | 是否倒序 |
| identifier | String | 否 | TrailingAlarm | 属性标识符 |
| startTime | Long | 否 | 1649299946000 | 开始时间 |
| endTime | Long | 否 | 1649299956000 | 结束时间 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| list | |||
| -name | String | 尾随告警 | 属性名称。 |
| -identifier | String | TrailingAlarm | 属性标识符。 |
| -type | String | float | 数据类型 |
| -value | String | 3295.0 | 采集值 |
| -time | Long | 1649299948000 | 采集值采集时间 |
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/queryDevicePropertyData?did=6890539992360259584&pageNum=1&pageSize=10
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"pageNum": 1,
"pageSize": 10,
"totalPages": 1,
"total": 2,
"list": [
{
"name": "沼气浓度",
"identifier": "ch4",
"type": "float",
"value": "0.0",
"time": 1652695059000
},
{
"name": "电压",
"identifier": "voltage",
"type": "float",
"value": "3295.0",
"time": 1652695059000
}
]
}
}
# 5.3.10 查询设备服务调用记录
调用该接口获取设备服务调用记录。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/thing/queryDeviceServiceData | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 示例 | 含义 |
|---|---|---|---|---|
| did | String | 否 | 6800675159679172608 | 设备ID。平台为该设备颁发的ID，设备的唯一标识符。 |
| deviceNumber | String | 否 | light | 设备名称。说明 如果传入该参数，需同时传入productKey。 |
| productKey | String | 否 | a1BwAGV | 设备所隶属的产品productKey。说明 如果传入该参数，需同时传入deviceNumber。 |
| pageNum | Integer | 是 | 1 | 页数 |
| pageSize | Integer | 是 | 10 | 每页显示的条数 最大为100 |
| isDesc | Boolean | 否 | true | 是否倒序 |
| identifier | String | 否 | AddKey | 服务标识符 |
| startTime | Long | 否 | 1649299946000 | 开始时间 |
| endTime | Long | 否 | 1649299956000 | 结束时间 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| list | |||
| -name | String | 尾随告警 | 服务名称。 |
| -identifier | String | TrailingAlarm | 服务标识符。 |
| -input | String | float | 服务输入参数 |
| -output | String | 3295.0 | 服务输出参数 |
| -messageId | Long | 1649299948000 | 消息id |
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/queryDeviceServiceData?did=6890539992360259584&pageNum=1&pageSize=10
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"pageNum": 1,
"pageSize": 10,
"totalPages": 1,
"total": 2,
"list": [
{
"name": "沼气浓度",
"identifier": "ch4",
"type": "float",
"value": "0.0",
"time": 1652695059000
},
{
"name": "电压",
"identifier": "voltage",
"type": "float",
"value": "3295.0",
"time": 1652695059000
}
]
}
}
# 5.4 物模型管理
请求路径
https://[host]:[port]/open/device-configuration/{api}
# 5.4.1 查询物模型TSL
调用该接口为查询产品对应物模型。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/thing/queryThingModel | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 是 | 产品Key |
返回的 data 消息体定义：
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| profile | ThingProfileDTO | 是 | 物模型概述 |
| properties | List<ThingElementDTO> | 是 | 属性列表 |
| events | List<ThingElementDTO> | 是 | 事件列表 |
| services | List<ThingElementDTO> | 是 | 服务列表 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/queryThingModel?productKey=Ysob4TcEyDN
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"profile": {
"version": "1",
"productKey": "Ysob4TcEyDN",
"productName": "智能门锁a110",
"authType": 1,
"modelCode": "yda110",
"cateCode": "ZNMSDEMO",
"protocolType": "1"
},
"properties": [
{
"identifier": "RemainBattery",
"name": "剩余电量",
"dataType": {
"type": "int32",
"specs": {
"min": "0",
"max": "100",
"step": "1"
}
},
"accessMode": "rw",
"required": 0,
"desc": "",
"method": "thing.event.property.post",
"elementType": 1,
"extDesc": "",
"isStandard": 0
}
],
"events": [
{
"identifier": "DoorOpenNotification",
"name": "开门通知",
"required": 0,
"desc": "",
"method": "thing.event.DoorOpenNotification.post",
"elementType": 2,
"eventType": 1,
"outputData": [
{
"identifier": "LockType",
"name": "开锁方式",
"type": "enum",
"specs": {
"0": "指纹",
"1": "密码",
"2": "卡",
"3": "机械钥匙"
},
"dataType": 2
},
{
"identifier": "KeyId",
"name": "钥匙ID",
"type": "text",
"specs": {
"length": "256"
},
"dataType": 2
}
],
"inputData": [],
"extDesc": "",
"isStandard": 0
}
],
"services": [
{
"identifier": "AddKey",
"name": "添加钥匙",
"required": 0,
"desc": "",
"method": "thing.service.AddKey",
"callType": 2,
"elementType": 3,
"outputData": [
{
"identifier": "KeyId",
"name": "钥匙ID",
"type": "text",
"specs": {
"length": "256"
},
"dataType": 2
}
],
"inputData": [
{
"identifier": "LockType",
"name": "开锁方式",
"type": "enum",
"specs": {
"0": "指纹",
"1": "密码",
"2": "卡",
"3": "机械钥匙"
},
"dataType": 1
},
{
"identifier": "UserLimit",
"name": "用户权限",
"type": "enum",
"specs": {
"1": "普通用户",
"2": "管理员"
},
"dataType": 1
}
],
"extDesc": "",
"isStandard": 0
}
]
}
}
# 5.5 OTA
请求路径
https://[host]:[port]/open/device-configuration/{api}
# 5.5.1 查询设备升级任务
获取设备当前升级任务信息
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/getUpgradeInfo | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 否 | 产品key |
| deviceNumber | String | 否 | 设备编码 |
| did | String | 否 | 设备did |
返回的 data 消息体定义：
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| packageId | String | PGI2Lk1Y6xHIS7lg0V7VDaqEKGyWcI | 升级包id |
| packageName | String | 睿讲升级包1 | 升级包名称 |
| packageType | Integer | 0 | 升级包类型 0-整包 |
| packageVersion | String | v2.0.1 | 升级包版本号 |
| versionCode | Integer | 1 | 版本编号 |
| isImportant | Integer | 0 | 是否关键版本 0:否 1:是 |
| fileSize | Long | 12517740 | 升级包大小 字节 |
| signatureAlgorithm | Integer | 0 | 签名算法 0-MD5 |
| signature | String | 18b2c6fe77dacd00f680ff0954ffcc5d | 签名 |
| description | String | 更新内容... | 升级包描述 |
| createTime | Long | 1623140684000 | 创建时间 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/getUpgradeInfo?did=cd5b278848bb44b3
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":{
"packageId":"PGI2Lk1Y6xHIS7lg0V7VDaqEKGyWcI",
"packageName":"睿讲升级包1",
"packageType":0,
"packageVersion":"v2.0.1",
"versionCode":0,
"isImportant":0,
"fileSize":12517740,
"signatureAlgorithm":0,
"signature":"18b2c6fe77dacd00f680ff0954ffcc5d",
"description":"1111",
"createTime":1623140684000
}
}
# 5.5.2 升级设备
远程升级设备
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/upgradeDevice | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 否 | 产品key |
| deviceNumber | String | 否 | 设备编码 |
| did | String | 否 | 设备did |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/upgradeDevice
{
"did":"123123xx"
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.6 设备日志
请求路径
https://[host]:[port]/open/device-configuration/{api}
# 5.6.1 触发设备上传日志
触发设备上传日志
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/triggerDeviceLogs | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 否 | 产品key |
| deviceNumber | String | 否 | 设备编码 |
| did | String | 否 | 设备did |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/triggerDeviceLogs
{
"did":"123123xx"
}
返回示例：
{
"msg":"操作成功",
"code":0
}
# 5.6.2 查询设备上传日志列表
触发设备上传日志
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/queryDeviceLogs | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| productKey | String | 否 | 产品key |
| deviceNumber | String | 否 | 设备编码 |
| did | String | 否 | 设备did |
| startTime | Lonng | 否 | 开始时间 |
| endTime | Lonng | 否 | 结束时间 |
| pageNum | Integer | 是 | 当前页数 |
| pageSize | Integer | 是 | 每页显示多少条 |
返回的 data 消息体定义：
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| id | Long | 1151 | 文件id |
| fileName | String | 17.log | 文件名称 |
| fileStatus | Integer | 1 | 日志状态 0:上传中 1:上传成功 2:上传失败 |
| createTime | Long | 1623140684000 | 创建时间 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDeviceLogs
{
"did":"123123xx",
"pageNum": 1,
"pageSize": 2
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":{
"pageNum":1,
"pageSize":2,
"totalPages":313,
"total":626,
"list":[
{
"id":1056,
"fileName":"log9.zip",
"fileStatus":1,
"createTime":1636972015000
},
{
"id":1055,
"fileName":"log1.zip",
"fileStatus":1,
"createTime":1636709450000
}
]
}
}
# 5.6.3 获取设备日志下载地址
触发设备上传日志
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/devices/downloadDeviceLogs | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| ids | List<long> | 是 | 文件id数组 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/downloadDeviceLogs
{
"ids":[
1001,1002
]
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":[
{
"id":123,
"downloadUrl":"https://intelligenthardware-stg.oss-cn-shenzhen.aliyuncs.com/10211/9ad2a14f-b3bf-4d2e-bfc9-7259655cbb69/log9.zip?response-content-disposition=attachment&Expires=1637634633&OSSAccessKeyId=LTAI4G3wdbddvj4skCK98UWP&Signature=iItvl2o7R29jOW2vPmMR138g6P0%3D"
}
]
}
# 5.7 场景联动
请求路径
https://[host]:[port]/open/rule-engine/{api}
# 5.7.1 创建规则
应用服务器可调用此接口在IoT PaaS创建一条规则，当指定设备上报的数据满足条件时，触发规则。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules | post |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| name | String | 是 | body | 参数说明：规则名称。 |
| description | String | 否 | body | 参数说明：规则的描述信息。 |
| triggers | List<Trigger> | 否 | body | 参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。 |
| conditions | List<RuleCondition> | 否 | body | 参数说明：规则的条件列表，单个规则最多支持设置10个条件。 |
| actions | List<RuleAction> | 是 | body | 参数说明：规则的动作列表，单个规则最多支持设置10个动作。 |
| ruleType | String | 是 | body | 参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。 |
| status | String | 是 | body | 参数说明：规则的状态，默认值：INACTIVE。取值范围：ACTIVE：激活。INACTIVE：未激活。 |
表 RuleTrigger
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则条件的类型。取值范围：DEVICE_TRIGGER：设备触发TIME_TRIGGER：时间触发 |
| deviceTrigger | DeviceTrigger Object | 否 | body | 参数说明：条件中设备数据类型的信息，当type为DEVICE_TRIGGER时，为必选参数 |
| timeTrigger | TimeTrigger Object | 否 | body | 参数说明：时间触发器信息 |
表 DeviceTrigger
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则条件的类型。取值范围：PROPERTY_TRIGGER：属性触发。EVENT_TRIGGER:事件触发。STATUS_TRIGGER:上下线触发 |
| deviceNumber | String | 否 | body | 参数说明：设备编码，用于唯一标识一个设备，在注册设备时由IoT PaaS分配获得。当ruleType为DEVICE_LINKAGE时，该参数值和productKey不能同时为空。如果该参数和productKey同时存在时，以该参数值对应的设备进行条件过滤。取值范围：长度不超过64，只允许字母、数字、下划线（）、连接符（-）的组合。取值范围：长度不超过64，只允许字母、数字、下划线（）、连接符（-）的组合。 |
| productKey | String | 是 | body | 参数说明：设备关联的产品ID，用于唯一标识一个产品模型，在管理门户导入产品模型后由平台分配获得。当ruleType为DEVICE_LINKAGE时，如果该参数和deviceNumber同时存在时，以deviceNumber参数值对应的设备进行条件过滤。 |
| propertyTrigger | Property (opens new window)Trigger Object | 否 | body | 参数说明：数据触发条件type为PROPERTY_TRIGGER时填写。为空：代表全部属性非空：按照实际属性判断 |
| statusTrigger | String | 否 | body | 参数说明：在线状态触发条件ON: 上线触发OFF：下线触发ALL: 上线线触发 |
| eventTrigger | EventTrigger Object | 否 | body | 参数说明：事件触发条件type为EVENT_TRIGGER时填写。为空：代表全部事件非空：按照事件条件判断 |
表 Property (opens new window)Trigge
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：设备属性的标识符 |
| operator | String | 是 | body | 参数说明：数据比较的操作符。取值范围：支持的操作符有：>，<，>=，<=，=和between:表示数值区间。 |
| value | String | 是 | body | 参数说明：数据比较表达式的右值。与数据比较操作符between联用时，右值表示最小值和最大值，用逗号隔开，如“20,30”表示大于等于20小于30。 |
表 EventTrigger
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：事件的标识符 |
表 timeTrigger
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| cron | String | 是 | body | 参数说明：cron表达式Cron表达式填写方式：Cron表达式仅支持5位，不支持秒；您可以参考 详细表达式 (opens new window) |
表 RuleCondition
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则条件的类型。取值范围：DEVICE_PROPERTY：设备数据类型条件。TIME_RANGE：规则条件触发的有效时间段 |
| devicePropertyCondition | DevicePropertyCondition Object | 否 | body | 参数说明：条件中设备数据类型的信息，当type为DEVICE_PROPERTY时，为必选参数 |
| timeRange | TimeRange Object | 否 | body | 参数说明：规则条件触发的有效时间段当type为TIME_RANGE时，为必选参数 |
表 DevicePropertyCondition
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| deviceNumber | String | 否 | body | 参数说明：设备编码，用于唯一标识一个设备，在注册设备时由IoT PaaS分配获得。当ruleType为DEVICE_LINKAGE时，该参数值和productKey不能同时为空。如果该参数和productKey同时存在时，以该参数值对应的设备进行条件过滤。 取值范围：长度不超过64，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
| productKey | String | 是 | body | 参数说明：设备关联的产品ID，用于唯一标识一个产品模型，在管理门户导入产品模型后由平台分配获得。当ruleType为DEVICE_LINKAGE时，如果该参数和deviceNumber同时存在时，以deviceNumber参数值对应的设备进行条件过滤。 |
| propertyFilter | PropertyFilter Object | 是 | body | 参数说明：数据过滤条件 |
表 PropertyFilter
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：设备属性的标识符 |
| operator | String | 是 | body | 参数说明：数据比较的操作符。取值范围：支持的操作符有：>，<，>=，<=，=和between:表示数值区间。 |
| value | String | 是 | body | 参数说明：数据比较表达式的右值。与数据比较操作符between联用时，右值表示最小值和最大值，用逗号隔开，如“20,30”表示大于等于20小于30。 |
表 TimeRange
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| rangeType | String | 是 | body | 参数说明：范围类型 TIME：时间类型（startTime和endTime必填） WEEK_DAY：周类型 （daysOfWeek必填） |
| startTime | String | 否 | body | 参数说明：时间可以从任意一个字段开始填，之前的字段用“”占位，之后字段必须全部填写，起始时间和结束时间省略的字段需要保持一致，否则视为非法输入。例如起始时间输入***-- 18:00:00，结束时间输入****-- 21:00:00，表示从规则创建的天开始，每一天的18点到21点为执行条件。 |
| endTime | String | 否 | body | 参数说明：时间可以从任意一个字段开始填，之前的字段用“”占位，之后字段必须全部填写，起始时间和结束时间省略的字段需要保持一致，否则视为非法输入。例如起始时间输入***-- 18:00:00，结束时间输入****-- 21:00:00，表示从规则创建的天开始，每一天的18点到21点为执行条件。 |
| daysOfWeek | String | 否 | body | 参数说明：周几 可选项为1-7，分表代表周一至周日，多选的情况下以逗号“,” 进行拼接 |
表 RuleAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则动作的类型。取值范围：DEVICE_PROPERTY_ACTION：下发设备属性设置消息类型。ALARM_ACTION：上报设备告警消息类型。当选择该类型时，condition中必须有DEVICE_PROPERTY条件类型。该类型动作只能唯一。RULE_ID_ACTION: 执行触发规则 |
| devicePropertyAction | DevicePropertyAction Object | 否 | body | 参数说明：下发设备命令消息内容。当type为DEVICE_PROPERTY_ACTION时，必填。 |
| alarmAction | AlarmAction Object | 否 | body | 参数说明：上报设备告警消息内容。当type为ALARM_ACTION时，必填。 |
| ruleIdAction | RuleIdAction Object | 否 | body | 参数说明：执行触发规则。当type为RULE_ID_ACTION时，必填。 |
表 DevicePropertyAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| deviceNumber | String | 是 | body | 参数说明：下发属性命令的设备ID。 |
| productKey | String | 是 | body | 参数说明：下发属性命令的产品Key。 |
| propertyAction | PropertyActionObject | 是 | body | 参数说明：下发属性命令信息。 |
表 PropertyAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：设备属性标识符。 |
| value | String | 是 | body | 参数说明：设备属性的值 |
| delayTime | Integer | 否 | body | 取值范围 0 ~ 86400 秒 |
表 RuleIdAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | body | 参数说明：规则Id |
| actionType | String | 是 | body | 参数说明：规则动作 触发:TRIGGER、启用:ACTIVE、停用:INACTIVE |
| delayTime | Integer | 否 | body | 取值范围 0 ~ 86400 秒 |
表 AlarmAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| alarmId | String | 是 | body | 参数说明:告警Id |
| delayTime | Integer | 否 | body | 取值范围 0 ~ 86400 秒 |
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| name | String | 是 | body | 参数说明：告警名称。 |
| alarmStatus | String | 是 | body | 参数说明：告警状态。取值范围：fault：上报告警。recovery：恢复告警。 |
| severity | String | 是 | body | 参数说明：告警级别。取值范围：minor（一般）、major（严重）和critical（致命）。 |
| description | String | 否 | body | 参数说明：告警的描述信息。 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| ruleId | String | 规则id。 | |
| name | String | 规则名称。 | |
| description | String | 规则的描述信息。 | |
| triggers | List<RuleTrigger> | 参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。 | |
| conditions | List<RuleCondition> | 参数说明：规则的条件列表，单个规则最多支持设置10个条件。 | |
| actions | List<RuleAction> | 参数说明：规则的动作列表，单个规则最多支持设置10个动作。 | |
| ruleType | String | 参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。 | |
| status | String | 参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。 | |
| lastUpdateTime | long | 规则最后更新时间，时间搓。（ms） | |
| edgeNodeDevice | List<EdgeNodeDevice> | 归属边缘侧节点设备列表。 |
表 EdgeNodeDevice
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| did | String | 是 | body | 参数说明:设备did |
| productKey | String | 是 | body | 参数说明:产品Key |
| deviceNumber | String | 是 | body | 参数说明:设备编码 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules
{
"name":"测试规则",
"description":"desc",
"productKey":"",
"projectId":"",
"triggers":[
{
"deviceTrigger":{
"propertyTrigger":{
"identifier":"CO2",
"operator":">",
"value":"10"
},
"eventTrigger":{
"identifier":null,
"outputDataIdentifier":null,
"operator":null,
"value":null
},
"productKey":"625MmdVruV4",
"deviceNumber":"eee0000000000111",
"type":"PROPERTY_TRIGGER"
},
"timeTrigger":{
},
"type":"DEVICE_TRIGGER"
}
],
"conditions":[
{
"devicePropertyCondition":{
"propertyFilter":{
"identifier":null
},
"productKey":null,
"deviceNumber":null
},
"timeRange":{
"rangeType":"WEEK_DAY",
"daysOfWeek":"6,7"
},
"type":"TIME_RANGE"
}
],
"actions":[
{
"devicePropertyAction":{
"propertyAction":{
"identifier":"WorkStatus",
"value":"1"
},
"productKey":"Gk11757LUkf",
"deviceNumber":"kk20220825"
},
"ruleIdAction":{
},
"alarmAction":null,
"type":"DEVICE_PROPERTY_ACTION"
}
],
"status":"INACTIVE",
"ruleType":"DEVICE_LINKAGE"
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":{
"ruleId":"1610573365187497985",
"name":"测试规则",
"description":"desc",
"triggers":[
{
"type":"DEVICE_TRIGGER",
"deviceTrigger":{
"type":"PROPERTY_TRIGGER",
"deviceNumber":"eee0000000000111",
"productKey":"625MmdVruV4",
"propertyTrigger":{
"identifier":"CO2",
"operator":">",
"value":"10"
},
"statusTrigger":null,
"eventTrigger":{
"identifier":null,
"outputDataIdentifier":null,
"operator":null,
"value":null
}
},
"timeTrigger":{
"cron":null
}
}
],
"conditions":[
{
"type":"TIME_RANGE",
"devicePropertyCondition":{
"deviceNumber":null,
"productKey":null,
"propertyFilter":{
"identifier":null,
"operator":null,
"value":null
}
},
"timeRange":{
"rangeType":"WEEK_DAY",
"startTime":null,
"endTime":null,
"daysOfWeek":"6,7 "
}
}
],
"actions":[
{
"type":"DEVICE_PROPERTY_ACTION",
"devicePropertyAction":{
"deviceNumber":"kk20220825",
"productKey":"Gk11757LUkf",
"propertyAction":{
"identifier":"WorkStatus",
"value":"1",
"delayTime":null
}
},
"alarmAction":null,
"ruleIdAction":{
"ruleId":null,
"actionType":null,
"delayTime":null
}
}
],
"ruleType":"DEVICE_LINKAGE",
"status":"INACTIVE",
"lastUpdateTime":1672825587924,
"edgeNodeDevice":[
],
"projectId":"",
"productKey":""
}
}
# 5.7.2 查询规则列表
应用服务器可调用此接口查询IoT PaaS中设置的规则列表。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules | get |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| limit | Integer | 否 | body | 参数说明：当前获取的条数限制取值范围：1-50的整数，默认值为10，最大获取50条数据。 |
| last | String | 否 | body | 参数说明：上一次分页查询结果中最后一条规则的ID。为空：则默认从起始位置开始获取规则。否则：从last的后一条数据开始获取分页数据。 |
| did | String | 否 | body | 参数说明:设备did |
| productKey | String | 否 | body | 参数说明:产品Key （当通过三元组信息筛选时，该值必填） |
| deviceNumber | String | 否 | body | 参数说明:设备编码（当通过三元组信息筛选时，该值必填） |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| last | String | 最后一条规则的id | |
| rules | List<RuleResponse> | 规则信息列表。 |
表1 RuleResponse
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| ruleId | String | 规则id。 | |
| name | String | 规则名称。 | |
| description | String | 规则的描述信息。 | |
| triggers | List<RuleTrigger> | 参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。 | |
| conditions | List<RuleCondition> | 参数说明：规则的条件列表，单个规则最多支持设置10个条件。 | |
| actions | List<RuleAction> | 参数说明：规则的动作列表，单个规则最多支持设置10个动作。 | |
| ruleType | String | 参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。 | |
| status | String | 参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。 | |
| lastUpdateTime | long | 规则最后更新时间，时间搓。（ms） | |
| edgeNodeDevice | List<EdgeNodeDevice> | 归属边缘侧节点设备列表。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules?last=1608359102519668737&limit=1
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"last": "1610573365187497985",
"rules": [
{
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "6,7 "
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "INACTIVE",
"lastUpdateTime": 1672825588000,
"edgeNodeDevice": [],
"projectId": "",
"productKey": ""
}
]
}
}
# 5.7.3 查询规则
应用服务器可调用此接口查询IoT PaaS中指定规则的配置信息。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules/{ruleId} | get |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | path | 参数说明：规则ID，用于唯一标识一条规则，在创建规则时由IoT PaaS分配获得。取值范围：长度不超过32，只允许字母、数字的组合。 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| ruleId | String | 规则id。 | |
| name | String | 规则名称。 | |
| description | String | 规则的描述信息。 | |
| triggers | List<RuleTrigger> | 参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。 | |
| conditions | List<RuleCondition> | 参数说明：规则的条件列表，单个规则最多支持设置10个条件。 | |
| actions | List<RuleAction> | 参数说明：规则的动作列表，单个规则最多支持设置10个动作。 | |
| ruleType | String | 参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。 | |
| status | String | 参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。 | |
| lastUpdateTime | long | 规则最后更新时间，时间搓。（ms） | |
| edgeNodeDevice | List<EdgeNodeDevice> | 归属边缘侧节点设备ID列表。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules/1610573365187497985
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "6,7 "
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "INACTIVE",
"lastUpdateTime": 1672825588000,
"edgeNodeDevice": [],
"projectId": "",
"productKey": ""
}
}
# 5.7.4 修改规则
应用服务器可调用此接口修改IoT PaaS中指定规则的配置。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules/{ruleId} | put |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | path | 参数说明：规则ID，用于唯一标识一条规则，在创建规则时由IoT PaaS分配获得。取值范围：长度不超过32，只允许字母、数字的组合。 |
| name | String | 是 | body | 参数说明：规则名称。 |
| description | String | 否 | body | 参数说明：规则的描述信息。 |
| triggers | List<RuleTrigger> | 否 | body | 参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。 |
| conditions | List<RuleCondition> | 否 | body | 参数说明：规则的条件列表，单个规则最多支持设置10个条件。 |
| actions | List<RuleAction> | 是 | body | 参数说明：规则的动作列表，单个规则最多支持设置10个动作。 |
| ruleType | String | 是 | body | 参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。 |
| status | String | 是 | body | 参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| ruleId | String | 规则id。 | |
| name | String | 规则名称。 | |
| description | String | 规则的描述信息。 | |
| triggers | List<RuleTrigger> | 参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。 | |
| conditions | List<RuleCondition> | 参数说明：规则的条件列表，单个规则最多支持设置10个条件。 | |
| actions | List<RuleAction> | 参数说明：规则的动作列表，单个规则最多支持设置10个动作。 | |
| ruleType | String | 参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。 | |
| status | String | 参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。 | |
| lastUpdateTime | long | 规则最后更新时间，时间搓。（ms） | |
| edgeNodeDevice | List<EdgeNodeDevice> | 归属边缘侧节点设备ID列表。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules/1610573365187497985
{
"name":"测试规则",
"description":"desc",
"triggers":[
{
"type":"DEVICE_TRIGGER",
"deviceTrigger":{
"type":"PROPERTY_TRIGGER",
"deviceNumber":"eee0000000000111",
"productKey":"625MmdVruV4",
"propertyTrigger":{
"identifier":"CO2",
"operator":">",
"value":"10"
},
"statusTrigger":null,
"eventTrigger":{
"identifier":null,
"outputDataIdentifier":null,
"operator":">",
"value":"10"
}
},
"timeTrigger":{
"cron":null
}
}
],
"conditions":[
{
"type":"TIME_RANGE",
"devicePropertyCondition":{
"deviceNumber":null,
"productKey":null,
"propertyFilter":{
"identifier":null,
"operator":null,
"value":null
}
},
"timeRange":{
"rangeType":"WEEK_DAY",
"startTime":null,
"endTime":null,
"daysOfWeek":"5"
}
}
],
"actions":[
{
"type":"DEVICE_PROPERTY_ACTION",
"devicePropertyAction":{
"deviceNumber":"kk20220825",
"productKey":"Gk11757LUkf",
"propertyAction":{
"identifier":"WorkStatus",
"value":"1",
"delayTime":null
}
},
"alarmAction":{
"alarmId":null,
"delayTime":null
},
"ruleIdAction":{
"ruleId":null,
"actionType":null,
"delayTime":null
}
}
],
"ruleType":"DEVICE_LINKAGE",
"status":"INACTIVE",
"lastUpdateTime":1672825588000,
"edgeNodeDevice":[
],
"projectId":"",
"productKey":""
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "5"
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "INACTIVE",
"lastUpdateTime": 1672883218085,
"edgeNodeDevice": [],
"projectId": "",
"productKey": ""
}
}
# 5.7.5 删除规则
应用服务器可调用此接口删除IoT PaaS中的指定规则。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules/{ruleId} | delete |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | path | 参数说明：规则ID，用于唯一标识一条规则，在创建规则时由IoT PaaS分配获得。取值范围：长度不超过32，只允许字母、数字的组合。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules/1610573365187497985
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "5"
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "INACTIVE",
"lastUpdateTime": 1672883218085,
"edgeNodeDevice": [],
"projectId": "",
"productKey": ""
}
}
# 5.7.6 修改规则状态
应用服务器可调用此接口删除IoT PaaS中的指定规则。该状态代表的是云端的运行状态，如果active，代表会按照触发器的规则进行触发运行，如果触发器为空则只能手动（接口）触发。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules/{ruleId}/status | put |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | path | 参数说明：规则ID，用于唯一标识一条规则，在创建规则时由IoT PaaS分配获得。取值范围：长度不超过32，只允许字母、数字的组合。 |
| status | String | 是 | body | 参数说明：规则的激活状态。取值范围：ACTIVE：激活。INACTIVE：未激活。 |
返回数据
| 名称 | 类型 | 含义 |
|---|---|---|
| status | String | 规则的激活状态。active：激活。inactive：未激活。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules/1610573365187497985/status
{
"status": "ACTIVE"
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "5"
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "ACTIVE",
"lastUpdateTime": 1672883218000,
"edgeNodeDevice": [],
"projectId": "",
"productKey": ""
}
}
边缘节点/网关API
# 5.7.7 设备绑定规则
应用服务器可调用此接口把指定的规则绑定到设备上面，IoT PaaS会把规则下发到设备。
一旦绑定了设备的规则，在云端必须是非激活状态。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules/{ruleId}/bind | put |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | path | 参数说明：规则ID，用于唯一标识一条规则，在创建规则时由IoT PaaS分配获得。取值范围：长度不超过32，只允许字母、数字的组合。 |
| did | String | 否 | body | 参数说明:边缘设备的did （did或三元组信息二选） |
| productKey | String | 否 | body | 参数说明:产品Key （当通过三元组信息筛选时，该值必填） |
| deviceNumber | String | 否 | body | 参数说明:设备编码（当通过三元组信息筛选时，该值必填） |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules/1610573365187497985/bind
{
"did": "6222123"
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "5"
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "ACTIVE",
"lastUpdateTime": 1672883218000,
"edgeNodeDevice": [
{
"deviceNumber": "1111111",
"did": "6222123",
"productKey": "dwqfwq"
}
],
"projectId": "",
"productKey": ""
}
}
# 5.7.8 设备解除绑定规则
应用服务器可调用此接口把指定的规则解除绑定到设备上面。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules/{ruleId}/unbind | put |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | path | 参数说明：规则ID，用于唯一标识一条规则，在创建规则时由IoT PaaS分配获得。取值范围：长度不超过32，只允许字母、数字的组合。 |
| did | String | 否 | body | 参数说明:边缘设备的did （did或三元组信息二选） |
| productKey | String | 否 | body | 参数说明:产品Key （当通过三元组信息筛选时，该值必填） |
| deviceNumber | String | 否 | body | 参数说明:设备编码（当通过三元组信息筛选时，该值必填） |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules/1610573365187497985/unbind
{
"did": "6222123"
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "5"
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "ACTIVE",
"lastUpdateTime": 1672883218000,
"edgeNodeDevice": [],
"projectId": "",
"productKey": ""
}
}
# 5.7.9 触发指定规则
应用服务器可调用此接口触发边缘设备执行规则。该规则是需要
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/rules/{ruleId}/devices/trigger | put |
请求参数
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruleId | String | 是 | path | 参数说明：规则ID，用于唯一标识一条规则，在创建规则时由IoT PaaS分配获得。取值范围：长度不超过32，只允许字母、数字的组合。 |
| did | String | 否 | body | 参数说明:边缘设备的did （did或三元组信息二选） |
| productKey | String | 否 | body | 参数说明:产品Key （当通过三元组信息筛选时，该值必填） |
| deviceNumber | String | 否 | body | 参数说明:设备编码（当通过三元组信息筛选时，该值必填） |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/rule-engine/iot/rules/1610573365187497985/devices/trigger
{
"did": "6222123"
}
返回示例：
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"ruleId": "1610573365187497985",
"name": "测试规则",
"description": "desc",
"triggers": [
{
"type": "DEVICE_TRIGGER",
"deviceTrigger": {
"type": "PROPERTY_TRIGGER",
"deviceNumber": "eee0000000000111",
"productKey": "625MmdVruV4",
"propertyTrigger": {
"identifier": "CO2",
"operator": ">",
"value": "10"
},
"statusTrigger": null,
"eventTrigger": {
"identifier": null,
"outputDataIdentifier": null,
"operator": ">",
"value": "10"
}
},
"timeTrigger": {
"cron": null
}
}
],
"conditions": [
{
"type": "TIME_RANGE",
"devicePropertyCondition": {
"deviceNumber": null,
"productKey": null,
"propertyFilter": {
"identifier": null,
"operator": null,
"value": null
}
},
"timeRange": {
"rangeType": "WEEK_DAY",
"startTime": null,
"endTime": null,
"daysOfWeek": "5"
}
}
],
"actions": [
{
"type": "DEVICE_PROPERTY_ACTION",
"devicePropertyAction": {
"deviceNumber": "kk20220825",
"productKey": "Gk11757LUkf",
"propertyAction": {
"identifier": "WorkStatus",
"value": "1",
"delayTime": null
}
},
"alarmAction": {
"alarmId": null,
"delayTime": null
},
"ruleIdAction": {
"ruleId": null,
"actionType": null,
"delayTime": null
}
}
],
"ruleType": "DEVICE_LINKAGE",
"status": "ACTIVE",
"lastUpdateTime": 1672883218000,
"edgeNodeDevice": [
{
"deviceNumber": "1111111",
"did": "6222123",
"productKey": "dwqfwq"
}
],
"projectId": "",
"productKey": ""
}
}
# 5.8 设备分组管理
请求路径
https://[host]:[port]/open/device-configuration/{api}
# 5.8.1 查询分组详情
调用该接口查询分组详情。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/groups/queryDeviceGroupInfo | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| groupId | String | 是 | 分组ID |
返回的 data 消息体定义：
| 名称 | 类型 | 是否必填 | 含义 |
|---|---|---|---|
| deviceActive | Integer | 1 | 激活设备数量。 |
| deviceCount | Integer | 10 | 设备总数。 |
| deviceOnline | Integer | 0 | 在线设备数量。 |
| groupId | String | tDQvBJqbUyHs**** | 分组ID。 |
| groupName | String | aliyun | 分组名称。 |
| createTime | Long | 1606210222000 | 创建时间。 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/groups/queryDeviceGroupInfo?groupId=tDQvBJqbUyHs***
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":{
"deviceActive":1,
"deviceCount":10,
"deviceOnline":2,
"groupId":"tDQvBJqbUyHs",
"groupName":"传感器",
"createTime":1649299949000
}
}
# 5.8.2 查询分组中的设备列表
调用该接口查询分组中的设备列表。
| 相对 URI | HTTP 方式 |
|---|---|
| /iot/groups/queryDeviceListByDeviceGroup | get |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| groupId | String | 是 | 分组ID |
| pageNum | Integer | 是 | 当前页 起始页为1 |
| pageSize | Integer | 是 | 每页条数 最大值为100 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| -pageNum | Integer | 当前页 |
| -pageSize | Integer | 每页条数 |
| -totalPages | Integer | 总页数 |
| -total | Long | 总条数 |
| -list | List | 设备列表 |
| deviceName | String | 设备名称 |
| deviceNumber | String | 设备编码 |
| deviceName | String | 设备名称 |
| deviceSecret | String | 设备秘钥 |
| did | String | DID |
| productKey | String | 产品Key |
| modelCode | String | 产品型号编码 |
| createTime | Long | 创建时间 |
| updateTime | Long | 修改时间 |
| networkStatus | Integer | 在线状态 1：在线 2：离线 |
| enable | Integer | 启用状态 0已启用 1未启用 |
| version | String | 设备版本号 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/device-configuration/iot/groups/queryDeviceListByDeviceGroup?groupId=tDQvBJqbUyHs***&pageNum=1&pageSize=10
返回示例：
{
"id":"123",
"code":200,
"data":{
"pageNum":1,
"pageSize":10,
"totalPages":25,
"total":250,
"list":[
{
"deviceNumber":"万睿摄像头1",
"deviceName":"DJIEDN11120",
"deviceSecret":"wzir73vq140xmq4cc11pyjsl6gcy2rvt",
"did":"6736933959340392000",
"productKey":"O0EvS9jGGII",
"modelCode":"mj1010101",
"createTime":1606210222000,
"updateTime":1606210222000,
"networkStatus":1,
"enable":0,
"version":"1.0.1"
}
]
}
}
# 5.9 项目管理
请求路径
https://[host]:[port]/open/basic-data/{api}
# 5.9.1 创建项目
调用该接口创建项目。
| 相对 URI | HTTP 方式 |
|---|---|
| /projects | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| projectName | String | 是 | 项目名称 |
| abbreviation | String | 否 | 名称简称 |
| projectType | Integer | 否 | 项目类型，默认值0；0：住宅；1：商写 |
| longitude | Double | 否 | 项目经度 |
| latitude | Double | 否 | 项目纬度 |
| address | String | 否 | 地址 |
| adAreaCode | String | 否 | 行政区编码 |
| managementArea | Double | 否 | 管理面积 |
| sourceCode | String | 否 | 公共组件数据源code |
| code | String | 否 | 主数据编码 |
| shangqiCode | String | 否 | 商企编码 |
| srCode | String | 否 | 百川云编码 |
| parentId | Long | 否 | 上级项目id |
| projectFormat | Integer | 否 | 项目业态，默认值0；1：住宅；2：商业；3：城市 |
| takeOverTime | Long | 否 | 接管时间 |
| planningHouseholds | Integer | 否 | 规划总户数 |
| totalTakeOverRoom | Integer | 否 | 接管总户数 |
| staffing | Integer | 否 | 人员编制 |
| onDutyTotal | Integer | 否 | 在岗人数 |
| orgIds | Long[] | 否 | 组织ID数组 |
| projectCode | String | 是 | 项目编码 |
| dataSource | Integer | 是 | 数据来源，默认值1；1：自建数据；2：主数据 |
| userName | String | 否 | 用户名 |
| userId | Long | 否 | 用户ID |
返回的 data 消息体定义：
| 名称 | 类型 | 是否必填 | 含义 |
|---|---|---|---|
| data | Long | 是 | 项目ID |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/basic-data/projects
{
"projectCode":"i000163601",
"projectName":"Test1",
"address":"新一代产业园",
"orgIds":[
13
],
"projectFormat":2
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":245211
}
# 5.9.2 修改项目
调用该接口修改项目。
| 相对 URI | HTTP 方式 |
|---|---|
| /projects | put |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| id | Long | 是 | 项目ID |
| projectName | String | 是 | 项目名称 |
| abbreviation | String | 否 | 名称简称 |
| projectType | Integer | 否 | 项目类型，默认值0；0：住宅；1：商写 |
| longitude | Double | 否 | 项目经度 |
| latitude | Double | 否 | 项目纬度 |
| address | String | 否 | 地址 |
| adAreaCode | String | 否 | 行政区编码 |
| managementArea | Double | 否 | 管理面积 |
| sourceCode | String | 否 | 公共组件数据源code |
| code | String | 否 | 主数据编码 |
| shangqiCode | String | 否 | 商企编码 |
| srCode | String | 否 | 百川云编码 |
| parentId | Long | 否 | 上级项目id |
| projectFormat | Integer | 否 | 项目业态，默认值0；1：住宅；2：商业；3：城市 |
| takeOverTime | Long | 否 | 接管时间 |
| planningHouseholds | Integer | 否 | 规划总户数 |
| totalTakeOverRoom | Integer | 否 | 接管总户数 |
| staffing | Integer | 否 | 人员编制 |
| onDutyTotal | Integer | 否 | 在岗人数 |
| orgIds | Long[] | 否 | 组织ID数组 |
| projectCode | String | 是 | 项目编码 |
| dataSource | Integer | 是 | 数据来源，默认值1；1：自建数据；2：主数据 |
| userName | String | 否 | 用户名 |
| userId | Long | 否 | 用户ID |
返回的 data 消息体定义：
| 名称 | 类型 | 是否必填 | 含义 |
|---|---|---|---|
| data | Long | 是 | 项目ID |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/basic-data/projects
{
"id":245211
"projectCode":"i000163601",
"projectName":"Test1",
"address":"新一代产业园",
"orgIds":[
13
],
"projectFormat":2
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0
}
# 5.9.3 删除项目
调用该接口删除项目。
| 相对 URI | HTTP 方式 |
|---|---|
| /projects | delete |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| id | Long | 是 | 项目ID |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/basic-data/projects?id=245211
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0
}
# 5.10 空间管理
请求路径
https://[host]:[port]/open/basic-data/{api}
# 5.10.1 创建空间
调用该接口创建空间。
| 相对 URI | HTTP 方式 |
|---|---|
| /spaces | post |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| spaceName | String | 是 | 空间名称(必填） |
| spaceType | Integer | 是 | 空间类型(必填）10：围合，20：楼栋，30：单元，40：楼层，50：室内空间(51：，52，53,) 60:US街道 70:US河流管理 80:US管廊 90:US社区 100:US河段 110:US分段 120:US路段 130:US公园 140:US桥梁 150:US楼栋 160：US楼层 170：US空间 |
| innerSpaceType | String | 否 | 室内空间类型(空间类型为50时选填如：会议室 |
| innerSpaceTypeCode | String | 否 | 室内空间类型编码 |
| layoutName | String | 否 | 户型名称 |
| projectId | Long | 是 | 项目ID（必填） |
| parentId | Long | 是 | 父空间ID（必填；如果是在项目下，父空间ID传projectId） |
| sort | Integer | 否 | 排序(必填） |
| version | Integer | 否 | 版本号 |
| dataSource | Integer | 否 | 数据来源 1：自建，2：主数据 |
| code | String | 否 | 主数据编码 |
| sourceCode | String | 否 | 公共组件数据源code |
| longitude | Double | 否 | 经度 |
| latitude | Double | 否 | 纬度 |
| address | String | 否 | 地址 |
| spaceName | String | 是 | 空间名称(必填） |
| spaceCode | String | 否 | 空间Code默认不填 |
| parentPath | String | 否 | 父空间path(必填；如果是在项目下级，父空间path如: 21 |
| thirdPartyName | String | 否 | 第三方系统名称 |
| thirdPartySpaceCode | String | 否 | 第三方系统空间编码 |
返回的 data 消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| spaceName | String | 空间名称(必填） |
| spaceType | Integer | 空间类型(必填）10：围合，20：楼栋，30：单元，40：楼层，50：室内空间(51：，52，53,) 60:US街道 70:US河流管理 80:US管廊 90:US社区 100:US河段 110:US分段 120:US路段 130:US公园 140:US桥梁 150:US楼栋 160：US楼层 170：US空间 |
| innerSpaceType | String | 室内空间类型(空间类型为50时选填如：会议室 |
| innerSpaceTypeCode | String | 室内空间类型编码 |
| layoutName | String | 户型名称 |
| projectId | Long | 项目ID（必填） |
| parentId | Long | 父空间ID（必填；如果是在项目下，父空间ID传projectId） |
| sort | Integer | 排序(必填） |
| version | Integer | 版本号 |
| dataSource | Integer | 数据来源 1：自建，2：主数据 |
| code | String | 主数据编码 |
| sourceCode | String | 公共组件数据源code |
| longitude | Double | 经度 |
| latitude | Double | 纬度 |
| address | String | 地址 |
| Long | id | 空间ID |
| String | spaceCode | 空间编码 |
| LocalDateTime | createTime | 创建时间 |
| String | createUser | 创建人 |
| LocalDateTime | updateTime | 更新时间 |
| String | updateUser | 更新人 |
| String | path | 路径 |
| Integer | isDel | 0表示未删除；1删除 |
| String | linkName | 空间名路径 |
| String | thirdPartyName | 第三方系统名称 |
| Integer | parentSpaceType | 父级空间类型 |
| String | thirdPartySpaceCode | 第三方系统空间编码 |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/basic-data/spaces
{
"spaceType":20,
"spaceName":"test1空间",
"sort":1,
"projectId":245211,
"parentId":245211,
"parentPath":"245211,"
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0,
"data":{
"spaceName":"test1空间",
"spaceType":20,
"innerSpaceType":"",
"innerSpaceTypeCode":null,
"layoutName":"",
"projectId":245211,
"parentId":245211,
"sort":1,
"version":0,
"dataSource":1,
"code":"",
"sourceCode":"",
"longitude":null,
"latitude":null,
"address":null,
"userName":null,
"id":3257811,
"spaceCode":"s003257812",
"createTime":1659077975000,
"createUser":"test",
"updateTime":1659077975000,
"updateUser":"test",
"path":"245211,3257811,",
"isDel":0,
"linkName":null,
"thirdPartyName":null,
"parentSpaceType":null,
"thirdPartySpaceCode":null
}
}
# 5.10.2 修改空间
调用该接口修改空间。
| 相对 URI | HTTP 方式 |
|---|---|
| /spaces | put |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| id | Long | 是 | 空间ID |
| spaceCode | String | 否 | 空间code |
| spaceName | String | 是 | 空间名称(必填） |
| spaceType | Integer | 否 | 空间类型(必填）；10：期数，20：楼栋，30：单元，40：楼层，50：房屋 |
| sort | Integer | 否 | 排序(必填） |
| innerSpaceType | String | 否 | 室内空间类型(空间类型为50时选填如：会议室 |
| innerSpaceTypeCode | String | 否 | 室内空间类型编码 |
| layoutName | String | 否 | 户型名称 |
| version | Integer | 否 | 版本号 |
| code | String | 否 | 主数据编码 |
| sourceCode | String | 否 | 公共组件编码 |
| thirdPartyName | String | 否 | 第三方系统名称 |
| thirdPartySpaceCode | String | 否 | 第三方系统空间编码 |
| address | String | 否 | 地址 |
| parentId | Long | 否 | 父空间ID（必填；如果是在项目下，父空间ID传projectId） |
| path | String | 否 | 空间path |
返回的 data 消息体定义：
| 名称 | 类型 | 是否必填 | 含义 |
|---|---|---|---|
| data | Long | 是 | 项目ID |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/basic-data/spaces
{
"spaceType":20,
"spaceName":"test2空间",
"id":3257811,
"sort":1
}
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0
}
# 5.10.3 删除空间
调用该接口删除空间。
| 相对 URI | HTTP 方式 |
|---|---|
| /spaces | delete |
请求参数定义：
| 名称 | 类型 | 是否必选 | 含义 |
|---|---|---|---|
| id | Long | 是 | 项目ID |
示例
请求示例：
https://api-eg.smartihw.com:1443/open/basic-data/spaces?id=245211
返回示例：
{
"success":true,
"msg":"操作成功",
"code":0
}
# 6物模型数据订阅
# 6.1 AMQP
# 6.1.1 绑定关系定义
ExchangeName:{appkey}_thing
ExchangeType:Topic
QueueName：应用侧自行定义，约定以appkey作为队列前缀。
物模型通讯相关
设备属性上报通知RoutingKey:
{productKey}.basicData
设备事件上报通知RoutingKey:
{productKey}.event.{eventType}
设备服务返回值通知RoutingKey:
{productKey}.serviceResponse
设备管理相关
设备状态变化通知RoutingKey:
{productKey}.networkStatus
设备生命周期变更通知RoutingKey:
{productKey}.deviceLifecycle.{changedType}
产品管理相关
物模型生命周期变更通知RoutingKey:
{productKey}.modelLifecycle.{changedType}
告警中心
告警中心告警通知RoutingKey:
alarmCenter
# 6.1.2 变量说明
{appkey}：应用AppKey，由基础服务新增应用后获取。
{productKey}：产品key 如：79b69gtWO85
{eventType}：事件类型 information:信息 alarm:告警 fault:故障
{changedType}：变更类型 add:新增 update:修改 delete:删除
# 6.1.3 消息体定义
# 6.1.3.1 **物模型通讯\设备管理相关推送 **
以下由 [3.2.2 物模型TSL(智能门锁a110 )](#TSL Example) 作为示例依据
外层消息体定义:
| 名称 | 类型 | 是否非空 | 含义 |
|---|---|---|---|
| messageId | String | 是 | 消息ID |
| did | String | 是 | did 全局唯一的设备标识 |
| deviceNumber | String | 是 | 设备编码 设备颁发产品内唯一的标识 |
| typeCode | String | 是 | 设备型号编码 产品上指定的型号固定编码 |
| time | String | 是 | 上报时间 |
| identifier | String | 否 | 标识符（事件、服务特有） |
| projectCode | String | 否 | 项目编码 设备所属的项目编码，全局唯一 |
| cateCode | String | 否 | 品类编码 一类或多类产品对应的品类编码。 |
| body | Object | 否 | 内容 |
# 6.1.3.1.1 设备属性上报通知
RoutingKey：Ysob4TcEyDN.basicData
body定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| RemainBattery | Object | 属性标识符 剩余电量 |
| -value | Object | 属性值，具体内容由该属性的数据类型决定 |
| -time | Long | 值采集时间戳 |
{
"messageId":"LJZKF15G8M2u2Wf1",
"did":"6793736399557230592",
"deviceNumber":"19961znms0",
"typeCode":"yda110",
"time":1650948779000,
"projectCode":"i40123009",
"cateCode":"znms",
"body":{
"RemainBattery":{
"time":1650948778000,
"value":72
}
}
}
属性与物模型TSL的对应：
# 6.1.3.1.2 设备事件上报通知
RoutingKey：Ysob4TcEyDN.event.information
body定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| time | Long | 事件采集时间 |
| value | Object | 事件输出参数 |
| -LockType | Integer | 事件输出参数[0] 开锁方式 |
| -KeyId | String | 事件输出参数[1] 钥匙ID |
{
"messageId":"LJZKF15G8M2u2Wf1",
"did":"6924578564029308928",
"deviceNumber":"19961znms0",
"typeCode":"yda110",
"identifier":"DoorOpenNotification",
"time":1650961378565,
"projectCode":"i40123009",
"cateCode":"znms",
"body":{
"time":1650948778000,
"value":{
"LockType":1,
"KeyId":"fd456ff123"
}
}
}
事件与物模型TSL的对应：
# 6.1.3.1.3 设备服务返回值通知
RoutingKey：Ysob4TcEyDN.serviceResponse
body定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| id | String | 服务调用时响应的消息id |
| code | Integer | 状态码，200:正常 504:设备响应超时 |
| data | Object | 服务输出参数 |
| -KeyId | String | 服务输出参数[0] 钥匙ID |
{
"messageId":"LJZKF15G8M2u2Wf1",
"did":"6924578564029308928",
"deviceNumber":"19961znms0",
"typeCode":"yda110",
"identifier":"DoorOpenNotification",
"time":1650961378565,
"projectCode":"i40123009",
"cateCode":"znms",
"body":{
"id":"105917531",
"code":200,
"data":{
"KeyId":"fd456ff124"
}
}
}
异步服务回复与物模型TSL的对应：
# 6.1.3.1.4 设备状态变化通知
RoutingKey：Ysob4TcEyDN.networkStatus
body定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| networkStatus | Integer | 在线状态 1：在线 2：离线 |
{
"messageId":"LJZKF15G8M2u2Wf1",
"did":"6924578564029308928",
"deviceNumber":"19961znms0",
"typeCode":"yda110",
"time":1650961378565,
"projectCode":"i40123009",
"cateCode":"znms",
"body":{
"networkStatus":1
}
}
# 6.1.3.1.5 设备生命周期变更通知
RoutingKey：Ysob4TcEyDN.deviceLeftcycle.update
body定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| deviceName | String | 设备名称 |
| deviceNumber | String | 设备编码 |
| projectCode | String | 项目编号 |
| projectName | String | 项目名称 |
| did | String | DID |
| productKey | String | 产品Key |
| deviceSecret | String | 设备密钥 |
| productName | String | 产品名称 |
| deviceTypeCode | String | 设备类型编号 |
| spaceCode | String | 空间编号 |
| spaceName | String | 安装位置 |
| createTime | Date | 创建时间 |
| networkStatus | Integer | 在线状态 1：在线 2：离线 |
| usageStatus | Integer | 使用状态 0：使用中 1：维修中 2：报废 3：备用 4：启用 5：停用 |
| enable | Integer | 启停状态 0:启用 1：停用 |
| iccid | String | iccid卡号 |
| version | String | 设备版本号 |
| isMultipart | Integer | 是否为多组动参 0:否 1:是 |
| dynamicParams | Object/List | 如果为多组动参时，类型为List，否则为Object |
| -{identifier} | String | key为动参标识符，value为对应的值 |
{
"messageId":"LJZKF15G8M2u2Wf1",
"did":"6924578564029308928",
"deviceNumber":"19961znms0",
"typeCode":"yda110",
"time":1650961378565,
"projectCode":"i40123009",
"cateCode":"znms",
"body":{
"deviceName":"智能门锁a1102",
"deviceNumber":"19961znms0",
"projectCode":"i000161213",
"projectName":"智能运维作业项目",
"did":"6924578564029308928",
"productKey":"Ysob4TcEyDN",
"deviceSecret":"htjmjkzvb463ehhpdwur0mgia1toqn3r",
"productName":"智能门锁a110",
"deviceTypeCode":"yda110",
"spaceCode":"s000037010",
"spaceName":"智能运维一期|1栋|1层",
"createTime":1650948182000,
"networkStatus":1,
"usageStatus":0,
"version":"1.0.1",
"iccid":"12300123000"
}
}
# 6.1.3.2 告警中心告警推送
RoutingKey：alarmCenter
消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| alarmId | String | 告警id |
| name | String | 告警名称 |
| description | String | 告警描述 |
| level | String | 告警级别 普通:NORMAL 重要:IMPORTANT |
| ruleResponse | Object<RuleResponse> | 对应规则,见5.7场景联动规则实体定义 |
{
"alarmId":"6810833009898422272",
"name":"ZNDJ101009",
"description":1623829128879,
"level":1,
"ruleResponse":{
...
}
}
# 6.2 MQTT
# 6.2.1 登录认证
登录参数：
mqttClientId:appkey{appkey}|timestamp{timestamp}|noise{noise}
mqttUserName:{appkey}
mqttPassword:hmacSha1(mqttClientId,{appSecret})
其中：mqttClientId作为加密内容，appSecret作为加密密钥
示例：
当
appKey:YoW23tX4aA3BJG6Q
timestamp:1647968584000
noise:123
appSecret:a542b4fa-7e52-4698-b8d3-9126658ab2a6
则
mqttClientId:appkeyYoW23tX4aA3BJG6Q|timestamp1647968584000|noise123
mqttUserName:YoW23tX4aA3BJG6Q
mqttPassword:f84fbf4bbfa93d1c06f8ede9bc1bf33b16fa6811
# 6.2.2 Topic定义
物模型通讯相关
设备属性上报通知Topic:
{appkey}_thing/{productKey}/basicData
设备事件上报通知Topic:
{appkey}_thing/{productKey}/event/{eventType}
设备服务返回值通知Topic:
{appkey}_thing/{productKey}/serviceResponse
设备管理相关
设备状态变化通知Topic:
{appkey}_thing/{productKey}/networkStatus
设备生命周期变更通知Topic:
{appkey}_thing/{productKey}/deviceLifecycle/{changedType}
产品管理相关
物模型生命周期变更通知Topic:
{appkey}_thing/{productKey}/modelLifecycle/{changedType}
告警中心
告警中心告警通知Topic:
{appkey}_thing/alarmCenter
# 6.2.3 变量说明
{appkey}:应用AppKey，由基础服务新增应用后获取。
{appSecret}:应用秘钥
{timestamp}:毫秒值时间戳
{noise}:随机数
{productKey}：产品key 如：79b69gtWO85
{eventType}：事件类型 information:信息 alarm:告警 fault:故障
{changedType}：变更类型 add:新增 update:修改 delete:删除
# 6.2.3 消息体定义
与 [AMQP消息体定义](#AMQP Msg Payload)一致，详见 [6.1.3](#AMQP Msg Payload)