IoT 应用侧 API 文档 v1.0

1. 关于IoT

IoT服务于智慧社区、智慧园区、智慧城市等解决方案集成应用，对下通过设备直连、网关连接、第三方平台对接等方式，将海量设备数据采集上云，在云平台对数据进行存储、加工、处理，提供给解决方案进行快速组合封装。

平台是一个开放性的能力服务平台，其核心能力体现在设备接入、数据处理、应用能力和常用功能的标准化封装，支持多种物联网通讯协议：MQTT、HTTP等，支持海量接入终端传感、智能控制器等硬件设备。

方案架构

设备类型分为：直连设备、网关设备、网关子设备。

直连设备：支持设备按照MQTT或HTTP协议接入到IoT。
网关设备：网关设备目前只支持MQTT协议接入。
网关子设备：网关子设备不具备直接上云的能力，需要借助网关设备接入到IoT。

2. 应用接入流程

向 IoT 平台产品经理描述需求，申请对应环境的 AppKey 和 AppSecret 应用凭证。
按照 OpenApi 的规范调用对应的 api 进行操作，功能开发。

3. 配置物模型

3.1 物模型概述

3.1.1 物模型

物模型是平台为产品定义的数据模型，用于描述产品的功能。

3.1.2 功能说明

物模型是物理空间中的实体（如传感器、车载装置、楼宇、工厂等）在云端的数字化表示，从属性、服务和事件三个维度，分别描述了该实体是什么、能做什么、可以对外提供哪些信息。定义了物模型的这三个维度，即完成了产品功能的定义。

功能类型	说明
属性（Property）	用于描述设备运行时具体信息和状态。例如，环境监测设备所读取的当前环境温度、智能灯开关状态、电风扇风力等级等。属性可分为读写和只读两种类型，即支持读取和设置属性。
服务（Service）	指设备可供外部调用的指令或方法。服务调用中可设置输入和输出参数。输入参数是服务执行时的参数，输出参数是服务执行后的结果。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，例如执行某项特定的任务。服务分为异步和同步两种调用方式。
事件（Event）	设备运行时，主动上报给云端的信息，一般包含需要被外部感知和处理的信息、告警和故障。事件中可包含多个输出参数。例如，某项任务完成后的通知信息；设备发生故障时的温度、时间信息；设备告警时的运行状态等。事件可以被订阅和推送。

3.1.3 使用说明

平台通过定义一种物的描述语言来描述物模型模块和功能，称为 TSL（Thing Specification Language）。

物模型TSL文件格式为JSON。您可在平台产品详情页面，单击功能定义页签，单击物模型TSL，查看或导出JSON格式的TSL。相关字段说明，请参见物模型TSL字段说明。

3.2 TSL概述

3.2.1 物模型TSL字段说明

本文介绍物模型TSL文件中JSON字段及其详细说明。

说明：为了完整展示TSL的结构，以下示例中包含所有参数，不代表实际使用中可能出现的组合。参数后的文字为参数说明，非参数值。各参数的使用场景，请参见参数说明。

json

{
  "profile": {
    "productKey": "当前产品的ProductKey",
    "version": "版本号",
    "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 类型特有）。"
        }
      }
    }
  ],
  "events": [
    {
      "identifier": "事件唯一标识符",
      "name": "事件名称",
      "desc": "事件描述",
      "type": "事件类型: 信息（info）、告警（alert）、故障（error）",
      "required": "是否是标准功能的必选事件",
      "outputData": [
        {
          "identifier": "输出参数唯一标识符",
          "name": "输出参数名称",
          "dataType": {
            "type": "属性类型",
            "specs": {}
          }
        }
      ],
      "method": "事件对应的方法名称（根据identifier 生成）"
    }
  ],
  "services": [
    {
      "identifier": "服务唯一标识符",
      "name": "服务名称",
      "desc": "服务描述",
      "required": "是否是标准功能的必选服务",
      "callType": "1（同步调用）或2（异步调用）",
      "inputData": [
        {
          "identifier": "入参唯一标识符",
          "name": "入参名称",
          "dataType": {
            "type": "属性类型",
            "specs": {}
          }
        }
      ],
      "outputData": [
        {
          "identifier": "出参唯一标识符",
          "name": "出参名称",
          "dataType": {
            "type": "属性类型",
            "specs": {}
          }
        }
      ]
    }
  ]
}

3.2.2 物模型TSL示例

json

{
  "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": 2
        }
      ],
      "isStandard": 0
    }
  ]
}

3.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，不支持结构体嵌套。
array	数组。需声明数组内的元素类型、数组元素个数。元素类型支持int32、float、double、text或struct，需确保同一个数组元素类型相同。元素个数限制为1~512个。	[1, 2, 3, 4, 5, 6]
raw	透传类型。针对复杂数据类型使用透传。	{"a":{"b":[{"c":"d"}]}}

4. 云端通用开发指南

4.1 云端OpenApi通用鉴权机制

概述

平台提供云端接口来使用设备能力。向 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 产品经理申请）
提供资料：三方系统的名称能够获取的信息：appKey，appSecret
需要知道对接环境的服务名和接口地址

访问地址说明

// host,port：由对接的平台提供对应环境的地址
// service:目前是固定值 device-configuration
// 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: appKey123:TM2MWY5YN
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)为空字典

响应示例

json

{
  "msg": "操作成功",
  "code": 0,
  "data": {
    "did": "6736933959340392448",
    "projectCode": "44030049",
    "spaceCode": "1020000",
    "deviceTypeCode": "MJ1010111",
    "productId": 35
  }
}

4.2 JAVA示例代码

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.io.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
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 javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import lombok.extern.slf4j.Slf4j;
import org.springframework.util.DigestUtils;
import org.springframework.util.StringUtils;

@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 请求方式GETPOSTPUT。
     * @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平台API出错时，返回的错误信息。入参数据格式错误、超出限定值、入参缺少必需参数等错误修改，请参见具体API文档的请求参数描述。

4.5.1 客户端错误码

以4开头的错误码为客户端相关错误码。

错误码	描述
40400	请求资源不存在
40101	未登录
40102	未经授权: %s
42900	请求过多被限流

注：一般属于客户端编码错误没有按照协议要求或限制规范编码。

4.5.2 系统错误码

以5开头的错误码为服务端相关错误码。

错误码	描述
5000XX	一般是服务器内部错误通知对应的开发人员

注：一般属于IoT平台内部异常所导致，请联系IoT平台开发人员进行解决。

4.5.3 业务错误码

以2开头的错误码为服务端相关错误码。

错误码	描述
2001001	登录已失效
2001101	数据已存在
2001102	验证码错误
2001103	存在关联数据,不允许删除
2001104	数据不存在
2001105	用户名/密码错误
2001106	设备未在IoT授权,请授权后连接
2001107	账户已冻结
2001108	应用已锁定
2001201	已存在
2001202	通用错误码
2001203	不存在
2001301	失败
2001302	设备不存在
2001303	IoTHub异常
2001304	设备不在线
2001305	设备响应超时

注：该错误码代表正常的业务错误，一般具有业务处理意义的。客户端可以结合业务需求，选择性识别判断处理。

5. 云端IOTAPI

5.1 设备管理

5.1.1 API列表

API	描述
RegisterDevice	注册设备。（新增设备）
QueryDeviceDetail	查询设备详情。
DeleteDevice	删除设备(解除应用和设备的管理关系)
BatchGetDeviceState	批量获取设备在线状态
BatchActDevices	接口批量激活设备
BatchInActivateDevices	批量解除激活设备
GetThingTopo	查询网关设备的子设备列表。
AddThingTopo	增加网关设备拓扑关系。
RemoveThingTopo	移除网关设备或子设备所具有的拓扑关系。
QueryDevice	查询产品的设备列表
QueryDeviceByCondition	查询条件下的设备列表
GetDeviceStatus	获取设备的运行状态
UpdateDevice	调用该接口修改指定设备
GetGatewayBySubDevice	调用该接口查询子设备绑定的网关。
QueryDeviceDynamicParams	查询设备动态参数
SaveDeviceDynamicParams	保存设备动态参数
QueryDeviceTags	查询设备标签
UpsertDeviceTags	保存更新设备标签
DeleteDeviceTags	删除设备标签
QueryDeviceByTags	根据标签查询设备
/devices/v1/batch/add	批量添加设备
/devices/v1/batch/modify/name	批量修改设备名称
/devices/batch/dids	批量删除设备
/devices/v2/page	获取设备列表
/products/v2/getProductByCode/	通过标准品（SP）key获取产品列表

5.1.2 注册设备

调用该接口在指定产品下注册设备。

接口说明

注册设备指在物联网平台产品下添加设备。在指定产品下成功注册设备后，IoT平台为设备颁发全局唯一的设备ID（did），用来标识该设备。在进行与设备相关的操作时，您可能需要提供目标设备的did。您也可以使用ProductKey和设备名称。did的优先级高于ProductKey和DeviceNumber组合。

相对URI	HTTP方式
/iot/devices/registerDevice	post

添加单个设备

接口幂等

版本变更说明

2025-6-19 v1.6.3 更新项目编号、项目名称支持

请求参数定义：

名称	类型	是否必选	含义
projectCode	String	否	项目编号，未关联任何系统校验
projectName	String	否	项目名称，未关联任何系统校验
productKey	String	是	产品 Key
deviceNumber	String	是	设备编码
deviceName	String	否	设备名称
did	String	否	设备唯一标识 did
parentGatewayDid	String	否	父级网关 id
deviceSecret	String	否	设备秘钥

返回的data消息体定义：

名称	类型	含义
deviceNumber	String	SN 编码
productKey	String	产品 key
did	String	唯一 id
parentGatewayDid	String	所属网关 did
projectCode	String	项目编号
projectName	String	项目名称
deviceName	String	设备名称
modelCode	String	产品型号编码

示例

请求示例：

json

{
  "projectCode": "44030049",
  "productKey": "sdfwefEwq",
  "deviceNumber": "SJIF256120"
}

返回示例（新增成功）：

json

{
  "success": true,
  "msg": "该设备已存在无需手动添加，系统自动为您关联该设备的已有信息",
  "code": 0,
  "data": {
    "did": "7341000138657148928",
    "productKey": "piVzL9HoKHi",
    "deviceSecret": "oknklqi35ls06vwbpevbvhqm65a9df3",
    "deviceNumber": "4401020040060381",
    "productSecret": "L7kqxof2BRpo2s1K",
    "projectCode": "piVzL9HoKHi",
    "spaceCode": null,
    "deviceTypeCode": "ZHYQ040401",
    "modelCode": "ZHYQ040401",
    "deviceName": "IP CAMERA",
    "createTime": 1750230822000
  }
}

5.1.3 查询设备信息

调用该接口查询指定设备的详细信息。

相对URI	HTTP方式
/iot/devices/queryDeviceDetail	get

请求参数定义：

名称	类型	是否必选	含义
did	String	否	设备ID。平台为该设备颁发的ID，设备的唯一标识符，与deviceNumber任选其一
deviceNumber	String	否	设备编码。productKey+deviceNumber。与did任选其一。
productKey	String	否	产品Key。productKey+deviceNumber。与did任选其一。

返回的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	纬度

示例

请求示例：

https://api-eg.smartihw.com:1443/open/device-configuration/iot/devices/queryDeviceDetail?did=6905410181719****

返回示例：

json

{
  "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": "pmyd1hk92fm1gt6r33918ebfpmx23gkf",
    "deviceTypeCode": "VRNZD189001",
    "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.4 删除设备

调用该接口删除指定设备。

相对URI	HTTP方式
/iot/devices/deleteDevice	delete

请求参数定义：

名称	类型	是否必选	含义
did	String	是	设备全局唯一id

示例

请求示例：

/iot/devices/deleteDevice?did=6736933959340392448

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.5 批量获取设备在线状态

批量获取设备在线状态

相对URI	HTTP方式
/iot/devices/batchGetDeviceState	post

请求参数定义：

名称	类型	是否必选	含义
params	List	是	设备全局唯一id
did	String	否	设备ID。平台为该设备颁发的ID，设备的唯一标识符，与deviceNumber任选其一
deviceNumber	String	否	设备编码。productKey+deviceNumber。与did任选其一。

返回的data消息体定义：

名称	类型	含义
statusList	List	设备状态列表
- did	String	设备ID
- networkStatus	Integer	在线状态1：在线2：离线

示例

请求示例：

json

{
  "params": [
    { "did": "6905326322269036544" },
    { "deviceNumber": "D4AD2053FB7B_10", "productKey": "sdfwefEwq" }
  ]
}

返回示例：

json

{
  "msg": "操作成功",
  "code": 0,
  "data": {
    "statusList": [
      { "did": "6905326322269036544", "networkStatus": 1 },
      { "did": "6905326322269036544", "networkStatus": 1 }
    ]
  }
}

5.1.6 批量激活设备

调用该接口批量激活设备（注意：单个批次激活设备不能超过100台）。

相对URI	HTTP方式
/iot/devices/batchActDevices	post

请求参数定义：

名称	类型	是否必选	含义
List
projectCode	String	是	所属项目编号
spaceCode	String	否	所属空间编号
productKey	String	是	产品 Key
deviceNumber	String	是	设备编码

示例

请求示例：

json

[
  {
    "productKey": "sdfwefEwq",
    "deviceNumber": "SJIF256120",
    "projectCode": "i10101101"
  }
]

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.7 批量解除设备激活

调用该接口批量解除激活设备（注意：单个批次解除激活设备不能超过100台）。

相对URI	HTTP方式
/iot/devices/batchInActivateDevice	post

请求参数定义：

名称	类型	是否必选	含义
List
productKey	String	是	产品 Key
deviceNumber	String	是	设备编码

示例

请求示例：

json

[
  {
    "productKey": "sdfwefEwq",
    "deviceNumber": "SJIF256120"
  }
]

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.8 获取网关子设备列表

调用该接口查询指定网关设备的子设备列表。

相对URI	HTTP方式
/iot/v3/devices/getThingTopo	get

请求参数定义：

名称	类型	是否必选	含义
did	String	否	设备ID。平台为该设备颁发的ID，设备的唯一标识符，与deviceNumber任选其一
deviceNumber	String	否	设备编码。productKey+deviceNumber。与did任选其一。
productKey	String	否	产品Key。productKey+deviceNumber。与did任选其一。

示例

请求示例：

/iot/v3/devices/getThingTopo?did=6736933959340392448

返回的data消息体定义：

名称	类型	含义
List	List
did	String	设备全局唯一id
deviceNumber	String	设备编码
productKey	String	产品Key

返回示例：

json

{
  "msg": "操作成功",
  "code": 0,
  "data": [
    {
      "did": "6736933959340392448",
      "deviceNumber": "FHIQW5926",
      "productKey": "sdfsdfeHYR01"
    }
  ]
}

5.1.9 增加网关设备拓扑

调用该接口通知网关设备增加拓扑关系。

相对URI	HTTP方式
/iot/v2/devices/addThingTopo	post

请求参数定义：

名称	类型	是否必选	含义
gatewayDid	String	否	网关did设备的唯一标识符
gatewayDeviceNumber	String	否	网关DeviceNumber说明:如果传入该参数，需同时传入productKey
gatewayProductKey	String	否	网关产品key说明:如果传入该参数，需同时传入deviceNumber
deviceList	List	是	子设备集合
did	String	否	子设备did设备的唯一标识符。
deviceNumber	String	否	子设备DeviceNumber说明:如果传入该参数，需同时传入productKey
productKey	String	否	子设备产品key说明:如果传入该参数，需同时传入deviceNumber

示例

请求示例：

json

{
  "gatewayDid": "6905398671135748096",
  "deviceList": [
    { "did": "6905360446253969408" },
    { "did": "6905359941876326400" }
  ]
}

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.10 移除网关设备拓扑

调用该接口移除网关或子设备的拓扑关系。

相对URI	HTTP方式
/iot/devices/removeThingTopo	put

请求参数定义：

名称	类型	是否必选	含义
did	String	是	设备全局唯一id

示例

请求示例：

/iot/devices/removeThingTopo?did=6736933959340392448

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.11 查询产品设备列表

查询产品的设备列表。

相对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	是	设备版本号

示例

请求示例：

/iot/devices/queryDevice?did=6905326322269036544

返回示例：

json

{
  "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.12 查询指定条件设备列表

查询条件下的设备列表。

相对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	是	设备版本号

示例

请求示例：

/iot/devices/queryDeviceByCondition?projectCode=j1010101

返回示例：

json

{
  "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.13 获取设备运行状态

获取设备的运行状态

相对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：离线

示例

请求示例：

/iot/devices/getDeviceStatus?did=6736933959340392448

返回示例：

json

{
  "msg": "操作成功",
  "code": 0,
  "data": {
    "did": "6736933959340392448",
    "networkStatus": 1
  }
}

5.1.14 更新设备数据

调用该接口修改指定设备。标黄处字段，修改时填入设备当前最新信息

相对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时，则移除设备经度信息。

示例

请求示例：

json

{
  "id": "6736933959340392448",
  "spaceCode": "s45123001",
  "deviceName": "TEST0001",
  "usageStatus": 0,
  "projectCode": "i4121515",
  "longitude": "114.043339",
  "latitude": "22.553421"
}

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.15 查询子设备绑定网关

调用该接口查询子设备绑定的网关。

相对URI	HTTP方式
/iot/devices/getGatewayBySubDevice	get

请求参数定义：

名称	类型	是否必选	含义
did	String	是	设备全局唯一id

示例

请求示例：

/iot/devices/getGatewayBySubDevice?did=6736933959340392448

返回的data消息体定义：

名称	类型	含义
did	String	设备全局唯一id
deviceNumber	String	设备编码
productKey	String	产品Key

返回示例：

json

{
  "msg": "操作成功",
  "code": 0,
  "data": {
    "did": "6736933959340392448",
    "deviceNumber": "FHIQW5926",
    "productKey": "sdfsdFeHYR01"
  }
}

5.1.16 查询设备动参

查询设备动态参数

相对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为对应的值

示例

请求示例：

/iot/devices/queryDeviceDynamicParams?did=6736933959340392448

返回示例：

json

{
  "msg": "操作成功",
  "code": 0,
  "data": {
    "isMultipart": 0,
    "dynamicParams": {
      "loopnum": "1",
      "network_key": "1"
    }
  }
}

5.1.17 更新设备动参

保存更新设备动态参数

相对URI	HTTP方式
/iot/devices/saveDeviceDynamicParams	post

请求参数定义：

名称	类型	是否必选	含义
did	String	否	要调用服务的设备 ID。平台为该设备颁发的 ID，设备的唯一标识符。
productKey	String	否	设备编号。说明如果传入该参数，需同时传入 productKey。
deviceNumber	String	否	设备所隶属的产品 productKey。说明如果传入该参数，需同时传入 deviceNumber。
dynamicParams	Object/List	是	设备动参列表-[identifier]String是key为动参标识符，value为对应的值

示例

请求示例：

json

{
  "did": "6736933959340392448",
  "dynamicParams": {
    "loopnum": "1",
    "network_key": "1"
  }
}

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.18 查询设备标签

查询设备标签

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

示例

请求示例：

/iot/devices/queryDeviceTags?did=6736933959340392448

返回示例：

json

{
  "msg": "操作成功",
  "code": 0,
  "data": [
    {
      "tagKey": "loopnum",
      "tagValue": "1"
    },
    {
      "tagKey": "network_key",
      "tagValue": "DSAF1E51F5115FW"
    }
  ]
}

5.1.19 更新设备标签

保存更新设备标签

相对URI	HTTP方式
/iot/devices/upsertDeviceTags	post

请求参数定义：

名称	类型	是否必选	含义
did	String	否	要调用服务的设备 ID。平台为该设备颁发的 ID，设备的唯一标识符。
productKey	String	否	设备编号。说明如果传入该参数，需同时传入 productKey。
deviceNumber	String	否	设备所隶属的产品 productKey。说明如果传入该参数，需同时传入 deviceNumber。
deviceTags	list	是	设备标签列表
tagKey	String		标签 Key
tagValue	String		标签值

示例

请求示例：

json

{
  "did": "6736933959340392448",
  "deviceTags": [
    { "tagKey": "loopnum", "tagValue": "10" },
    { "tagKey": "network_key", "tagValue": "DSAF1E51F5115FW" }
  ]
}

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.20 删除设备标签

删除设备标签

相对URI	HTTP方式
/iot/devices/deleteDeviceTags	delete

请求参数定义：

名称	类型	是否必选	含义
did	String	否	设备 ID。平台为该设备颁发的 ID，设备的唯一标识符。
deviceNumber	String	否	设备编码。说明如果传入该参数，需同时传入 productKey。
productKey	String	否	设备所隶属的产品 productKey。说明如果传入该参数，需同时传入 deviceNumber。
tagKeys	List	是	要删除的设备标签

示例

请求示例：

json

{
  "did": "6736933959340392448",
  "tagKeys": [
    "loopnum",
    "network_key"
  ]
}

返回的data消息体定义：

名称	类型	含义
did	String	设备全局唯一 id
deviceNumber	String	设备编码
productKey	String	产品 Key

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.1.21 根据标签查询设备

根据标签查询设备

相对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
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	是	设备版本号

示例

请求示例：

json

{
  "did": "6736933959340392448",
  "deviceTags": [
    { "tagKey": "loopnum", "tagValue": "10" },
    { "tagKey": "network_key", "tagValue": "DSAF1E51F5115FW" }
  ]
}

返回示例：

json

{
  "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.22 批量添加设备

【POST】：/devices/v1/batch/add

批量添加设备，存在无法添加的设备时，全部无法添加成功

添加失败的设备，通过errMsg返回失败原因，仅失败设备返回

不支持添加设备时绑定网关
批量添加的设备在iot已存在时，
- 不报错、不修改，返回did
- 名称不一致时，更新名称为接口传入名称
- 接口入参指定did且与已存在的设备did不一致时，作为失败处理
有业务错误（校验不通过的情况），只返回错误的数据

路径请求参数说明

字段名	类型	说明
userName	String	操作人，非必填

请求示例： /devices/v1/batch/add?userName=abc

body:

字段名	类型	说明
deviceNumber	String	SN 编码
deviceName	String	设备名称
productKey	String	产品 key
did	String	唯一 id
parentGatewayName	String	所属网关
parentGatewayDid	String	所属网关 did
projectCode	String	项目编号，v1.6.3 后支持
projectName	String	项目名称，v1.6.3 后支持

请求示例

json

[
  { "deviceNumber": "test123", "productKey": "testPk" }
]

响应参数说明

字段名	类型	说明
deviceNumber	String	SN 编码
productKey	String	产品key
did	String	唯一id
parentGatewayDid	String	所属网关did
deviceName	String	设备名称
addFlag	boolean	true 添加成功；false 添加失败
errMsg	String	错误信息，仅添加失败响应

响应示例

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": [
    {
      "deviceNumber": "test123",
      "productKey": "testPk",
      "did": "did",
      "deviceName": "IotDeviceName",
      "errMsg": "添加失败,设备已存在，返回信息为iot 信息"
    }
  ]
}

5.1.23 批量修改设备名称

【PUT】：/devices/v1/batch/modify/name

修改的设备中，存在iot没有的设备时，全部修改失败

路径请求参数说明

字段名	类型	说明
userName	String	操作人，非必填
updateProject	Boolean	true：需要修改项目信息，false：不修改项目信息（默认false）v1.6.3 支持

请求示例： /devices/v1/batch/modify/name?userName=abc

请求参数说明

字段名	类型	说明
deviceName	String	设备名称
did	String	唯一 id
projectCode	String	项目编号，v1.6.3 支持
projectName	String	项目名称，v1.6.3 支持

请求示例

json

[
  { "deviceName": "newName", "did": "testDid" }
]

响应参数说明 参考批量添加

5.1.24 批量删除设备

【DELETE】/devices/batch/dids

删除不存在的设备时，也提示删除成功

请求参数说明

字段名	类型	说明
did	String	唯一 id

请求示例

json

[
  "did1",
  "did2"
]

响应参数说明

字段名	类型	说明
sucDids	List	删除成功 did
errDids	List	删除失败 did
notExistDids	List	不存在的设备 did

响应示例

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "sucDids": ["did1"],
    "errDids": [],
    "notExistDids": ["did2"]
  }
}

5.1.25 获取设备列表

20250418

【POST】/devices/v2/page

请求参数

字段名	类型	说明
cateCode	String	标准物模型产品类别编号查询时，isStandard 写死1，level 写死3
isStandard	Integer	通过标准品cateCode 查询时写死1
level	Integer	通过标准品cateCode 查询时写死3

请求示例：

json

{
  "pageNum": 1,
  "pageSize": 10,
  "cateCode": "standard",
  "isStandard": 1,
  "level": 3
}

响应参数说明

字段名	类型	说明
categoryCode	String	产品类别编号
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表示设备密匙
selfRegistration	Integer	自动注册：0关闭，1开启
isStandard	Integer	是否为标准品：0否，1是
cateCode	String	品类code
cateName	String	品类名称
modelName	String	产品型号
modelCode	String	型号编码
protocolCode	Integer	协议code
reportingCycle	Integer	数据判断周期，单位：秒
supplier	String	厂家
brand	String	品牌

响应示例

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 1642,
    "total": 16411,
    "list": [
      {
        "id": 38292,
        "did": "7320368765189844992",
        "deviceName": "示例配电柜5N2QQ18",
        "deviceNumber": "10x-18",
        "deviceSecret": "f96cmzd16m1o0d9qovuvd0aytrvwtg2h",
        "projectName": null,
        "projectCode": null,
        "spaceName": null,
        "spaceCode": null,
        "projectSpaceName": null,
        "networkStatus": 0,
        "usageStatus": 0,
        "latestMsgTimeStr": null,
        "latestMsgTime": null,
        "productName": "标准电表V1",
        "productKey": "q1yf0IMM9ri",
        "modelName": "biaozhundianbiaov1",
        "modelCode": "biaozhundianbiaov1",
        "standardCategoryName": null,
        "standardCategoryCode": null,
        "gatewayName": null,
        "gatewayId": null,
        "nodeType": 0,
        "subDeviceCount": null,
        "natEnable": false
      }
    ]
  }
}

5.1.26 通过标准品（SP）key获取产品列表

20250418

【GET】/products/v2/getProductByCode/{cateCode}

请求示例： https://xxx.com/open/device-configuration/products/v2/getProductByCode/abc

请求参数说明

字段名	类型	说明
cateCode	String	标准物模型产品类别编号

响应参数说明

字段名	类型	说明
id	Long	设备 ID
did	String	DID
deviceName	String	设备名称
deviceNumber	String	设备编码
deviceSecret	String	设备密钥
projectName	String	项目名称
projectCode	String	项目编码
spaceName	String	空间名称
spaceCode	String	空间编码
projectSpaceName	String	项目空间
networkStatus	Integer	联网状态: 0: - , 1: 正常, 2: 异常
usageStatus	Integer	使用状态: 0: 启用, 1: 停用
latestMsgTimeStr	String	最后一次通讯时间(字符串类型)
latestMsgTime	LocalDateTime	最后一次通讯时间
productName	String	产品名称
productKey	String	产品 key
modelName	String	产品型号名称
modelCode	String	产品型号编码
standardCategoryName	String	标准品类名称
standardCategoryCode	String	标准品类编码
gatewayName	String	关联网关名称
gatewayId	Long	网关 ID(子设备专有)
nodeType	Integer	产品节点类型
subDeviceCount	Integer	网关挂载的子设备数

5.2 产品管理

5.2.1 API列表

API	描述
QueryProduct	调用该接口查询指定产品的详情信息。
QueryProductList	调用该接口根据品类查询产品信息。
CreateProduct	调用该接口创建产品。
UpdateProduct	调用该接口修改指定产品的信息。
DeleteProduct	调用该接口删除指定产品。
UpsertProductTags	调用该接口创建或者更新产品标签列表
DeleteProductTags	调用该接口删除产品标签
ListProductTags	调用该接口查询产品标签

5.2.2 查询产品详细信息

调用该接口查询指定产品的详情信息。

相对URI	HTTP方式
/iot/products/queryProduct	get

请求参数定义：

名称	类型	是否必选	含义
productKey	String	否	产品 key
modelCode	String	否	产品型号编码

返回的数据信息定义：

名称	类型	含义
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***

返回示例：

json

{
  "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": "dsfgdsfdgdf",
    "protocolCode": 1,
    "protocolName": "MQTT",
    "reportingCycle": 111,
    "supplier": "海康",
    "brand": "海康",
    "createTime": 1652695059000,
    "updateTime": 1652695059000
  }
}

5.2.3 查询分组设备列表

调用该接口查询分组中的设备列表。

相对URI	HTTP方式
/iot/products/queryProductList	post

请求参数定义：

名称	类型	是否必选	含义
cateCodes	List	否	品类 code 集合
nodeCode	String	否	品类节点
nodeLevel	Integer	否	品类级别 1: 行业 2: 场景 3: 品类
isStandard	Integer	否	是否为标准品. 0 否 1 是
name	String	否	名称模糊搜索
productTagList	List	否	产品标签
status	Integer	否	发布状态: 0 未发布 1 已发布
pageNum	Integer	是	当前页起始页为 1
pageSize	Integer	是	每页条数最大值为 100

其中 TagKeyValueVo 对象属性如下：

字段名	类型	是否必选	说明
tagKey	String	否	标签 key
tagValue	String	否	标签 value

返回的数据消息体定义：

名称	类型	含义
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	产品型号名称

示例

请求示例：

json

{
  "cateCodes": ["gdfwfew"],
  "productTagList": [
    { "tagKey": "1", "tagValue": "" },
    { "tagKey": "1", "tagValue": "22" }
  ],
  "pageNum": 1,
  "pageSize": 10
}

返回示例：

json

{
  "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.4 创建产品

调用该接口创建产品。

相对URI	HTTP方式
/iot/products/createProduct	post

请求参数定义：

名称	类型	是否必选	含义
name	String	是	产品名称
nodeType	String	是	节点类型:0 直连设备 1 网关子设备 2 网关设备
networkMode	String	是	联网方式 0,以太网 1,蜂窝 (2G/3G/4G/5G)2,LoRaWAN5,modbus6,OPC UA7,ZigBee8,BLE9,其他 10,Wi-Fi11,OPC DA12,Bacnet13,自定义
authType	Integer	是	认证方式,1:一机一密,2:一型一密.
isStandard	Integer	是	是否为标准品.0 否 1 是
cateCode	String	否	品类 code 当为标准品时,该值必填
modelName	String	是	产品型号名称
modelCode	String	是	产品型号编码
protocolCode	Integer	是	协议 code1,MQTT2,万睿协议 3,IotHub4,其他 5,萤石云协议 6,云眸协议 7,智居协议 8,Lora 设备 9,Http10,CMP
reportingCycle	Integer	否	数据判断周期
supplier	String	否	厂家
brand	String	否	品牌
desc	String	否	产品描述
productKey	String	否	产品 key

返回的data消息体定义：

名称	类型	含义
productKey	String	产品 Key
productSecret	String	产品秘钥

示例

请求示例：

json

{
  "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"
}

返回示例：

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "productKey": "rPU4PHokGR3",
    "productSecret": "IC81m3ryC3k182Pz"
  }
}

5.2.5 更新产品

调用该接口修改指定产品的信息。

相对URI	HTTP方式
/iot/products/updateProduct	put

请求参数定义：

名称	类型	是否必选	含义
productKey	String	是	产品 key
name	String	是	产品名称
modelName	String	是	产品型号名称
reportingCycle	Integer	否	数据判断周期
supplier	String	否	厂家
brand	String	否	品牌
desc	String	否	产品描述

示例

请求示例：

json

{
  "productKey": "rPU4PHokGR3",
  "name": "测试井盖产品",
  "modelName": "菲尔斯特SJ1111",
  "brand": "菲尔斯特",
  "supplier": "菲尔斯特",
  "reportingCycle": "300",
  "nodeType": "0",
  "protocolCode": "1",
  "desc": "test"
}

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.2.6 删除产品

调用该接口删除指定产品。

相对URI	HTTP方式
/iot/products/deleteProduct	delete

请求参数定义：

名称	类型	是否必选	含义
productKey	String	是	产品 key

示例

请求示例：

/iot/products/deleteProduct?productKey=rPU4PHokGR3

返回示例：

json

{
  "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

示例

请求示例：

json

{
  "productKey": "4bcRb1u0dV6",
  "tagString": [
    { "tagKey": "3", "tagValue": "33" },
    { "tagKey": "2", "tagValue": "44" }
  ]
}

返回示例：

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0
}

5.2.8 删除产品标签

调用该接口删除产品标签信息。

相对URI	HTTP方式
/iot/products/deleteProductTags	post

请求参数定义：

名称	类型	是否必选	含义
productKey	String	是	产品 key
delTagKeyList	List	是	删除产品 key 列表

示例

请求示例：

json

{
  "productKey": "4bcRb1u0dV6",
  "delTagKeyList": ["3", "2"]
}

返回示例：

json

{
  "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

返回示例：

json

{
  "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	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***

返回示例：

json

{
  "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 物模型使用

5.3.1 API列表

API	描述
SetDeviceProperty	设置设备的属性。
InvokeThingService	调用该接口在一个设备上调用指定服务。
QueryDevicePropertyStatus	查询指定设备的属性快照。
BatchQueryDevicePropertyStatus	批量查询指定设备的属性快照。
GetDeviceShadow	查询设备影子
UpdateDeviceShadow	设置设备影子
QueryDeviceEventData	获取设备事件上报记录
QueryNearestDeviceEvent	获取设备事件的最新记录
QueryDevicePropertyData	获取设备属性上报记录
QueryDeviceServiceData	获取设备服务调用记录

5.3.2 设置设备属性

调用该接口为指定设备设置属性值。

相对URI	HTTP方式
/iot/thing/setDeviceProperty	post

返回结果说明

因为云端下发属性设置命令和设备收到并执行该命令是异步的，所以调用该接口时，返回的成功结果只表示云端下发属性设置的请求成功，不能保证设备端收到并执行了该请求。需设备端 SDK 成功响应云端设置设备属性值的请求，设备属性值才能真正设置成功。

请求参数

名称	类型	是否必选	示例值	描述
items	String	是		要设置的属性信息，数据格式为 JSON String。属性组成为属性标识符 key:属性值 value，多个属性用英文逗号隔开。例如，设置智能灯的如下两个属性：标识符为Switch的开关属性，数据类型为Bool，设置值为1（开）；标识符为Color的灯颜色属性，数据类型为String，设置值为blue。那么，Items={"Switch":1,"Color":"blue"}。
did	String	否	Q7u0hVRdZRRIDnTLv00100	设备ID。平台为该设备颁发的ID，设备的唯一标识符。DID作为设备唯一标识符，和ProductKey与DeviceNumber组合是一一对应的关系。如果您同时传入DID和ProductKey与DeviceNumber组合，则以DID为准。
deviceNumber	String	否	light	设备名称。说明如果传入该参数，需同时传入productKey。
productKey	String	否	a1BwAGV	设备所隶属的产品productKey。说明如果传入该参数，需同时传入deviceNumber。

返回数据

名称	类型	示例值	描述
code	Int		错误码
data	Struct		调用成功时，返回的数据。
requestId	String		平台为该请求生成的唯一标识符。
messageId	String		云端向设备下发服务调用的消息ID。
result	Struct
msg	String		错误信息。
success	Boolean	true	表示是否调用成功。·true：调用成功。·false：调用失败。

示例

参数示例

json

{
  "did": "6795983672244699136",
  "items": {"switch_1": true}
}

正常返回示例

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "requestId": "Mdo5CsA2FpOf82z9vCg022p31NU5SvE0",
    "messageId": "8TGZSr4G4Cd6x5jy",
    "result": null
  }
}

5.3.3 调用设备指定服务

调用该接口在一个设备上调用指定服务。

相对URI	HTTP方式
/iot/thing/invokeThingService	post

请求参数

名称	类型	是否必选	示例值	描述
args	String	是		要启用服务的入参信息，数据格式为 JSON String，例如 Args={"param1":1}。若此参数为空时，需传入 Args={}。
identifier	String	是	Set	服务的标识符。设备的服务Identifier，可在控制台中，设备所属的产品的功能定义中查看；或调用 QueryThingModel，从返回的物模型信息中查看。
did	String	否	6800675159679172608	要调用服务的设备ID。平台为该设备颁发的ID，设备的唯一标识符。
deviceNumber	String	否	light	设备编号。说明如果传入该参数，需同时传入productKey。
productKey	String	否	a1BwAGV	设备所隶属的产品 productKey。说明如果传入该参数，需同时传入 deviceNumber。

返回数据

名称	类型	示例值	描述
code	Int		错误码
data	Struct		调用成功时，返回的数据。
requestId	String		平台为该请求生成的唯一标识符。
messageId	String		云端向设备下发服务调用的消息 ID。
result	Struct		同步调用服务，返回的调用结果。异步调用服务，不返回此参数。
msg	String		错误信息。
success	Boolean	true	表示是否调用成功。·true：调用成功。·false：调用失败。

示例

请求示例

json

{
  "did": "6800675159679172608",
  "identifier": "saveVideo",
  "args": {
    "channelNo": "1",
    "startTime": 1621412750000,
    "endTime": 1621413110000,
    "voiceSwitch": "2"
  }
}

正常返回

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "requestId": "etD240V1sUI6Z05ycBjDw1j6Nd2H94Q0",
    "messageId": "or173pC954Ur3VTo",
    "result": {}
  }
}

5.3.4 查询设备属性

调用该接口查询指定设备的属性快照。

相对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	属性值。

示例

请求示例

json

{
  "did": "6800675159679172608"
}

正常返回示例

json

{
  "msg": "操作成功",
  "code": 0,
  "data": {
    "did": "1515151111111",
    "propertyStatusInfo": [
      {
        "value": "48",
        "time": "1579249151178",
        "identifier": "Humidity"
      },
      {
        "value": "32.46",
        "time": "1579249151178",
        "identifier": "Temperature"
      }
    ]
  }
}

5.3.5 批量查询设备属性

调用该接口批量查询设备的属性快照。

相对URI	HTTP方式
/iot/thing/batchQueryDevicePropertyStatus	post

请求参数

名称	类型	是否必选	示例值	描述
dids	List	否	[6800675159679172608]	要查询的设备 ID。平台为该设备颁发的 ID，设备的唯一标识符。

返回数据

名称	类型	示例值	描述
did	String	6800675159679172***	设备 did
propertyStatusInfo
identifier	String	Temperture	属性标识符。
time	String	1517553572362	属性修改的时间，单位是毫秒。
value	Object	25	属性值。

示例

请求示例

json

{
  "dids": ["6800675159679172608"]
}

正常返回示例

json

{
  "msg": "操作成功",
  "code": 0,
  "data": [
    {
      "did": "6800675159679172***",
      "propertyStatusInfo": [
        {
          "value": "48",
          "time": "1579249151178",
          "identifier": "Humidity"
        },
        {
          "value": "32.46",
          "time": "1579249151178",
          "identifier": "Temperature"
        }
      ]
    }
  ]
}

5.3.6 查询设备影子

调用该接口查询指定设备的影子信息。

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

返回示例：

json

{
  "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.7 更新设备影子

调用该接口修改指定设备的影子信息。

相对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	是	期望的影子状态

请求示例：

json

{
  "did": "6741996731459698688",
  "shadow": {
    "method": "update",
    "state": {
      "desired": {
        "color": "green"
      }
    },
    "version": 2
  }
}

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.3.8 获取设备事件上报记录

调用该接口获取设备事件上报记录。

相对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		事件输出参数
time	Long	1649299948000	事件采集时间

请求示例：

https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/queryDeviceEventData?did=6914083768374407168&identifier=TrailingAlarm&pageNum=1&pageSize=10

返回示例：

json

{
  "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.9 获取设备最新事件记录

调用该接口获取设备事件的最新记录。

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

返回示例：

json

{
  "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.10 获取设备属性上报记录

调用该接口获取设备事件上报记录。

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

返回示例：

json

{
  "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.11 查询设备事件上报记录

调用该接口获取设备事件上报记录。

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

返回示例：

json

{
  "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 物模型管理

API 列表

API	描述
QueryThingModel	调用该接口查看指定产品物模型中的功能定义详情。

5.4.1 查询产品物模型

调用该接口为查询产品对应物模型。

相对URI	HTTP方式
/iot/thing/queryThingModel	get

请求参数定义：

名称	类型	是否必选	含义
productKey	String	是	产品Key

返回的data消息体定义：

名称	类型	示例值	描述
profile	ThingProfileDTO	是	物模型概述
properties	List	是	属性列表
events	List	是	事件列表
services	List	是	服务列表

示例

请求示例：

https://api-eg.smartihw.com:1443/open/device-configuration/iot/thing/queryThingModel?productKey=Ysob4TcEyDN

返回示例：

json

{
  "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": 2
          }
        ],
        "isStandard": 0
      }
    ]
  }
}

5.5 OTA升级

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	创建时间

示例

请求示例：

/iot/devices/getUpgradeInfo?did=cd5b278848bb44b3

返回示例：

json

{
  "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

请求参数定义：

名称	类型	是否必选	含义
did	String	是	设备did
version	String	否	升级版本

示例

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.6 设备日志

5.6.1 触发设备日志上传

触发设备上传日志

相对URI	HTTP方式
/iot/devices/triggerDeviceLogs	post

请求参数定义：

名称	类型	是否必选	含义
productKey	String	否	产品 key
deviceNumber	String	否	设备编码
did	String	否	设备 did

示例

返回示例：

json

{
  "msg": "操作成功",
  "code": 0
}

5.6.2 查询设备日志

查询设备日志

相对URI	HTTP方式
/iot/devices/queryDeviceLogs	get

请求参数定义：

名称	类型	是否必选	含义
productKey	String	否	产品 key
deviceNumber	String	否	设备编码
did	String	否	设备 did
startTime	Long	否	开始时间
endTime	Long	否	结束时间
pageNum	Integer	是	当前页数
pageSize	Integer	是	每页显示多少条

返回的data消息体定义：

名称	类型	含义
id	Long	文件id
fileName	String	文件名称
status	Integer	文件状态
createTime	Long	创建时间

返回示例：

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "pageNum": 1,
    "pageSize": 2,
    "totalPages": 313,
    "total": 626,
    "list": [
      {
        "id": 1056,
        "fileName": "log9.zip",
        "status": 1,
        "createTime": 1636972015000
      },
      {
        "id": 1055,
        "fileName": "log1.zip",
        "status": 1,
        "createTime": 1636709450000
      }
    ]
  }
}

5.6.3 下载设备日志

设备日志下载

相对URI	HTTP方式
/iot/devices/downloadDeviceLogs	get

请求参数定义：

名称	类型	是否必选	含义
ids	List	是	文件 id 数组

示例

返回示例：

json

{
  "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&0SSAccessKeyId=LTAI4G3wdbddvj4skCK98UWP&Signature=iTtv1z07R29j0W2vPmMR138g6P0%3D"
    }
  ]
}

5.7 场景联动

5.7.1 创建规则

应用服务器可调用此接口在物联网平台创建一条规则，当指定设备上报的数据满足条件时，触发规则。

相对URI	HTTP方式
/iot/rules	post

请求参数

名称	类型	是否必选	位置	含义
name	String	是	body	参数说明：规则名称。
description	String	否	body	参数说明：规则的描述信息。
triggers	List	否	body	参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。
conditions	List	否	body	参数说明：规则的条件列表，单个规则最多支持设置10个条件。
actions	List	是	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	参数说明：设备编码，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。当ruleType为DEVICE_LINKAGE时，该参数值和productKey不能同时为空。如果该参数和productKey同时存在时，以该参数值对应的设备进行条件过滤。取值范围：长度不超过64，只允许字母、数字、下划线（_）、连接符（-）的组合。
productKey	String	是	body	参数说明：设备关联的产品ID，用于唯一标识一个产品模型，在管理门户导入产品模型后由平台分配获得。当ruleType为DEVICE_LINKAGE时，如果该参数和deviceNumber同时存在时，以deviceNumber参数值对应的设备进行条件过滤。
propertyTrigger	PropertyTrigger Object	否	body	参数说明：数据触发条件type为PROPERTY_TRIGGER时填写。为空：代表全部属性非空：按照实际属性判断
statusTrigger	String	否	body	参数说明：在线状态触发条件ON:上线触发；OFF：下线触发；ALL:上线线触发
eventTrigger	EventTrigger Object	否	body	参数说明：事件触发条件type为EVENT_TRIGGER时填写。为空：代表全部事件非空：按照事件条件判断

表 PropertyTrigger

名称	类型	是否必选	位置	含义
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位，不支持秒；您可以参考详细表达式

表 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	参数说明：设备编码，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。当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,2,3,4,5" 表示周一至周五

表 RuleAction

名称	类型	是否必选	位置	含义
type	String	是	body	参数说明：规则动作的类型。取值范围：DEVICE_PROPERTY_ACTION：下发设备属性设置消息类型。ALARM_ACTION：上报设备告警消息类型。当选择该类型时，condition中必须有DEVICE_PROPERTY条件类型。该类型动作只能唯一。RULE_ID_ACTION：执行触发规则
devicePropertyAction	DevicePropertyAction	否	body	参数说明：下发设备命令消息内容。当type为DEVICE_PROPERTY_ACTION时，必填。
alarmAction	AlarmAction	否	body	参数说明：上报设备告警消息内容。当type为ALARM_ACTION时，必填。
ruleIdAction	RuleIdAction	否	body	参数说明：执行触发规则。当type为RULE_ID_ACTION时，必填。

表 DevicePropertyAction

名称	类型	是否必选	位置	含义
deviceNumber	String	是	body	参数说明：下发属性命令的设备编码。
productKey	String	是	body	参数说明：设备的产品Key。
propertyAction	PropertyAction	是	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	参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。
conditions	List	参数说明：规则的条件列表，单个规则最多支持设置10个条件。
actions	List	参数说明：规则的动作列表，单个规则最多支持设置10个动作。
ruleType	String	参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。
status	String	参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。
lastUpdateTime	long	规则最后更新时间，时间搓。（ms）
edgeNodeDeviceList	List	归属边缘侧节点设备列表。

表 EdgeNodeDevice

名称	类型	是否必选	位置	含义
did	String	是	body	参数说明:设备 did
productKey	String	是	body	参数说明:产品 Key
deviceNumber	String	是	body	参数说明:设备编码

5.7.2 查询规则列表

应用服务器可调用此接口查询物联网平台中设置的规则列表。

相对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		规则信息列表。

表1 RuleResponse

名称	类型	描述
ruleId	String	规则 id。
name	String	规则名称。
description	String	规则的描述信息。
triggers	List	参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。
conditions	List	参数说明：规则的条件列表，单个规则最多支持设置10个条件。
actions	List	参数说明：规则的动作列表，单个规则最多支持设置10个动作。
ruleType	String	参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。
status	String	参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。
lastUpdateTime	long	规则最后更新时间，时间搓。（ms）
edgeNodeDeviceList	List	归属边缘侧节点设备列表。

5.7.3 查询规则

应用服务器可调用此接口查询物联网平台中指定规则的配置信息。

相对URI	HTTP方式
/iot/rules/	get

请求参数

名称	类型	是否必选	位置	含义
ruleId	String	是	path	参数说明：规则ID，用于唯一标识一条规则，在创建规则时由物联网平台分配获得。取值范围：长度不超过32，只允许字母、数字的组合。

返回数据

名称	类型	描述
ruleId	String	规则 id。
name	String	规则名称。
description	String	规则的描述信息。
triggers	List	参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。
conditions	List	参数说明：规则的条件列表，单个规则最多支持设置10个条件。
actions	List	参数说明：规则的动作列表，单个规则最多支持设置10个动作。
ruleType	String	参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。
status	String	参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。
lastUpdateTime	long	规则最后更新时间，时间搓。（ms）
edgeNodeDeviceList	List	归属边缘侧节点设备ID列表。

5.7.4 修改规则

应用服务器可调用此接口修改物联网平台中指定规则的配置。

相对URI	HTTP方式
/iot/rules/	put

请求参数

名称	类型	是否必选	位置	含义
ruleId	String	是	path	参数说明：规则ID，用于唯一标识一条规则，在创建规则时由物联网平台分配获得。取值范围：长度不超过32，只允许字母、数字的组合。
name	String	是	body	参数说明：规则名称。
description	String	否	body	参数说明：规则的描述信息。
triggers	List	否	body	参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。
conditions	List	否	body	参数说明：规则的条件列表，单个规则最多支持设置10个条件。
actions	List	是	body	参数说明：规则的动作列表，单个规则最多支持设置10个动作。
ruleType	String	是	body	参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。
status	String	是	body	参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。

返回数据

名称	类型	描述
ruleId	String	规则id。
name	String	规则名称。
description	String	规则的描述信息。
triggers	List	参数说明：规则的触发器列表，单个规则最多支持设置10个触发器。
conditions	List	参数说明：规则的条件列表，单个规则最多支持设置10个条件。
actions	List	参数说明：规则的动作列表，单个规则最多支持设置10个动作。
ruleType	String	参数说明：规则的类型取值范围：DEVICE_LINKAGE：设备联动。
status	String	参数说明：规则的状态，默认值：active。取值范围：ACTIVE：激活。INACTIVE：未激活。
lastUpdateTime	long	规则最后更新时间，时间搓。（ms）
edgeNodeDeviceList	List	归属边缘侧节点设备ID列表。

5.7.5 删除规则

应用服务器可调用此接口删除物联网平台中的指定规则。

相对URI	HTTP方式
/iot/rules/	delete

请求参数

名称	类型	是否必选	位置	含义
ruleId	String	是	path	参数说明：规则ID，用于唯一标识一条规则，在创建规则时由物联网平台分配获得。取值范围：长度不超过32，只允许字母、数字的组合。

返回数据

返回code 200

5.7.6 修改规则状态

应用服务器可调用此接口删除物联网平台中的指定规则。该状态代表的是云端的运行状态，如果active，代表会按照触发器的规则进行触发运行，如果触发器为空则只能手动（接口）触发。

相对URI	HTTP方式
/iot/rules/{ruleId}/status	put

请求参数

名称	类型	是否必选	位置	含义
ruleId	String	是	path	参数说明：规则ID，用于唯一标识一条规则，在创建规则时由物联网平台分配获得。取值范围：长度不超过32，只允许字母、数字的组合。
status	String	是	body	参数说明：规则的激活状态。取值范围：ACTIVE：激活。INACTIVE：未激活。

返回数据

名称	类型	含义
status	String	规则的激活状态。active：激活。inactive：未激活。

5.7.7 设备绑定规则

应用服务器可调用此接口把指定的规则绑定到设备上面，物联网平台会把规则下发到设备。

一旦绑定了设备的规则，在云端必须是非激活状态。

相对URI	HTTP方式
/iot/rules/{ruleId}/bind	put

请求参数

名称	类型	是否必选	位置	含义
ruleId	String	是	path	参数说明：规则 ID，用于唯一标识一条规则，在创建规则时由物联网平台分配获得。取值范围：长度不超过32，只允许字母、数字的组合。
did	String	否	body	参数说明:边缘设备的 did（did 或三元组信息二选）
productKey	String	否	body	参数说明:产品 Key（当通过三元组信息筛选时，该值必填）
deviceNumber	String	否	body	参数说明:设备编码（当通过三元组信息筛选时，该值必填）

返回数据

返回code 200

5.7.8 设备解除绑定规则

应用服务器可调用此接口把指定的规则解除绑定到设备上面。

相对URI	HTTP方式
/iot/rules/{ruleId}/unbind	put

请求参数

名称	类型	是否必选	位置	含义
ruleId	String	是	path	参数说明：规则 ID，用于唯一标识一条规则，在创建规则时由物联网平台分配获得。取值范围：长度不超过32，只允许字母、数字的组合。
did	String	否	body	参数说明:边缘设备的 did（did 或三元组信息二选）
productKey	String	否	body	参数说明:产品 Key（当通过三元组信息筛选时，该值必填）
deviceNumber	String	否	body	参数说明:设备编码（当通过三元组信息筛选时，该值必填）

返回数据

返回code 200

5.7.9 触发指定规则

应用服务器可调用此接口触发边缘设备执行规则。该规则是需要

相对URI	HTTP方式
/iot/rules/{ruleId}/devices/trigger	put

请求参数

名称	类型	是否必选	位置	含义
ruleId	String	是	path	参数说明：规则ID，用于唯一标识一条规则，在创建规则时由物联网平台分配获得。取值范围：长度不超过32，只允许字母、数字的组合。
did	String	否	body	参数说明:边缘设备的 did（did 或三元组信息二选）
productKey	String	否	body	参数说明:产品 Key（当通过三元组信息筛选时，该值必填）
deviceNumber	String	否	body	参数说明:设备编码（当通过三元组信息筛选时，该值必填）

返回数据

返回code 200

5.8 设备分组管理

5.8.1 API列表

API	描述
QueryDeviceGroupInfo	调用该接口查询分组详情。
QueryDeviceListByDeviceGroup	调用该接口查询分组中的设备列表。

5.8.2 查询分组详情

调用该接口查询分组详情。

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

返回示例：

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "deviceActive": 1,
    "deviceCount": 10,
    "deviceOnline": 2,
    "groupId": "tDqVBJqbUyHs",
    "groupName": "传感器",
    "createTime": 1649299949000
  }
}

5.8.3 查询分组设备列表

调用该接口查询分组中的设备列表。

相对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	设备编码
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

返回示例：

json

{
  "id": "123",
  "code": 200,
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 25,
    "total": 250,
    "list": [
      {
        "deviceNumber": "万睿摄像头1",
        "deviceName": "DJIEDN11120",
        "deviceSecret": "wzir73vq140xmq4cc11pyjs16gcy2rvt",
        "did": "6736933959340392000",
        "productKey": "0OEvS9jGGII",
        "modelCode": "mj1010101",
        "createTime": 1606210222000,
        "updateTime": 1606210222000,
        "networkStatus": 1,
        "enable": 0,
        "version": "1.0"
      }
    ]
  }
}

5.9 节点配置

5.9.1 获取节点类型

【GET】/edge/enable

是否作为云边协同边端节点

无入参

响应参数

data

true，为开启云边协同，可以同步产品设备
false，关闭云边协同，不同步产品设备

响应示例

json

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": "true"
}

6. 物模型数据订阅

6.1 AMQP

6.1.1 绑定关系定义

Exchange Name: {appkey}_thing
Exchange Type: Topic
Queue Name: 约定以应用 key 作为队列前缀

物模型通讯相关

通知类型	RoutingKey
设备属性上报通知	{productKey}.basicData
设备事件上报通知	{productKey}.event.
设备服务返回值通知	{productKey}.serviceResponse

设备管理相关

通知类型	RoutingKey
设备状态变化通知	{productKey}.networkStatus
设备生命周期变更通知	{productKey}.deviceLifecycle.
设备影子变更通知	{productKey}.deviceShadow/change

产品管理相关

通知类型	RoutingKey
物模型生命周期变更通知	{productKey}.modelLifecycle.

告警中心

通知类型	RoutingKey
告警中心告警通知	alarmCenter

6.1.2 变量说明

变量	说明
	应用 AppKey，由基础服务新增应用后获取。
	应用秘钥
	毫秒值时间戳
	随机数
	产品 key 如：79b69gtW085
	事件类型 information: 信息 alarm: 告警 fault: 故障
	变更类型 add: 新增 update: 修改 delete: 删除

6.1.3 消息体定义

基础消息体结构

名称	类型	是否非空	含义
did	String	是	did
deviceNumber	String	是	设备编码
typeCode	String	是	设备型号编码
time	String	是	上报时间
identifier	String	否	标识符（事件、服务特有）
projectCode	String	否	项目编码
cateCode	String	否	品类编码
body	Object	否	内容

示例：设备属性上报通知

RoutingKey: Ysob4TcEyDN.basicData

body定义：

名称	类型	含义
RemainBattery	Object	属性标识符剩余电量
value	Object	属性值，具体内容由该属性的数据类型决定
time	Long	值采集时间戳

消息示例：

json

{
  "deviceNumber": "199612nms0",
  "typeCode": "yda110",
  "time": 1650948779000,
  "projectCode": "i40123009",
  "cateCode": "znms",
  "body": {
    "RemainBattery": {
      "time": 1650948778000,
      "value": 72
    }
  }
}

示例：设备事件上报通知

RoutingKey: Ysob4TcEyDN.event.information

body定义：

名称	类型	含义
time	Long	事件采集时间
value	Object	事件输出参数
LockType	Integer	事件输出参数[0] 开锁方式
KeyId	String	事件输出参数[1] 钥匙ID

消息示例：

json

{
  "did": "6924578564029308928",
  "deviceNumber": "19961znms0",
  "typeCode": "yda110",
  "identifier": "DoorOpenNotification",
  "time": 1650961378565,
  "projectCode": "i40123009",
  "cateCode": "znms",
  "body": {
    "time": 1650948778000,
    "value": {
      "LockType": 1,
      "KeyId": "fd456ff123"
    }
  }
}

示例：设备服务返回值通知

RoutingKey: Ysob4TcEyDN.serviceResponse

body定义：

名称	类型	含义
id	String	服务调用时响应的消息id
code	Integer	状态码，200:正常 504:设备响应超时
data	Object	服务输出参数
KeyId	String	服务输出参数[0] 钥匙ID

消息示例：

json

{
  "did": "6924578564029308928",
  "deviceNumber": "19961znms0",
  "typeCode": "yda110",
  "identifier": "DoorOpenNotification",
  "time": 1650961378565,
  "projectCode": "i40123009",
  "cateCode": "znms",
  "body": {
    "id": "123456",
    "code": 200,
    "data": {
      "KeyId": "fd456ff123"
    }
  }
}

示例：设备状态变化通知

RoutingKey: Ysob4TcEyDN.networkStatus

body定义：

名称	类型	含义
networkStatus	Integer	在线状态1：在线2：离线

消息示例：

json

{
  "did": "6924578564029308928",
  "deviceNumber": "199612nms0",
  "typeCode": "yda110",
  "time": "1650961378565",
  "projectCode": "i40123009",
  "cateCode": "znms",
  "body": {
    "networkStatus": 1
  }
}

示例：设备生命周期变更通知

RoutingKey: Ysob4TcEyDN.deviceLifecycle.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：停用
iccid	String	iccid 卡号
version	String	设备版本号
isMultipart	Integer	是否为多组动参 0:否 1:是
dynamicParams	Object/List	如果为多组动参时，类型为 List，否则为 Object
	String	key 为动参标识符，value 为对应的值

消息示例：

json

{
  "did": "6924578564029308928",
  "deviceNumber": "199612nms0",
  "typeCode": "yda110",
  "time": 1650961378565,
  "projectCode": "i40123009",
  "cateCode": "znms",
  "body": {
    "deviceName": "智能门锁 a1102",
    "deviceNumber": "199612nms0",
    "projectCode": "i000161213",
    "projectName": "智能运维作业项目",
    "did": "6924578564029308928",
    "productKey": "Ysob4TceyDN",
    "deviceSecret": "htjmjkzvb463ehhpdwur@mgia1toqn3r",
    "productName": "智能门锁 a110",
    "deviceTypeCode": "yda110",
    "spaceCode": "s000037010",
    "spaceName": "智能运维一期|1栋|1层",
    "createTime": 1650948182000,
    "networkStatus": 1,
    "usageStatus": 0,
    "version": "1.0.1",
    "iccid": "12300123000"
  }
}

示例：告警中心告警通知

RoutingKey: alarmCenter

消息体定义：

名称	类型	含义
alarmId	String	告警 id
name	String	告警名称
description	String	告警描述
level	String	告警级别普通:NORMAL 重要:IMPORTANT
ruleResponse	Object	对应规则,见场景联动查询规则实体定义

消息示例：

json

{
  "alarmId": "6810833009898422272",
  "name": "ZNDJ101009",
  "description": 1623829128879,
  "level": 1,
  "ruleResponse": {}
}

示例：设备影子变化通知

RoutingKey: Ysob4TcEyDN.deviceShadow

消息体定义：

属性	描述
desired	设备的预期状态。仅当设备影子文档具有预期状态时，才包含desired部分。应用程序向desired部分写入数据，更新事物的状态，而无需直接连接到该设备。
reported	设备的报告状态。设备可以在reported部分写入数据，报告其最新状态。应用程序可以通过读取该参数值，获取设备的状态。JSON文档中也可以不包含reported部分，没有reported部分的文档同样为有效影子JSON文档。
metadata	当用户更新设备状态文档后，设备影子服务会自动更新metadata的值。设备状态的元数据的信息包含以Epoch时间表示的每个属性的时间戳，用来获取准确的更新时间。
timestamp	影子文档的最新更新时间。
version	用户主动更新版本号时，设备影子会检查请求中的version值是否大于当前版本号。如果大于当前版本号，则更新设备影子，并将version值更新到请求的版本中，反之则会拒绝更新设备影子。该参数更新后，版本号会递增，用于确保正在更新的文档为最新版本。version参数为long型。为防止参数溢出，您可以手动传入-1将版本号重置为0。

6.2 MQTT

6.2.1 登录认证

参数	取值
mqttClientId
mqttUserName
mqttPassword	hmacsha1({appSecret}, {appkey})

示例

当

appKey: YoW23tX4aA3BJG6Q
timestamp: 1647968584000
noise: 123
appSecret: a542b4fa-7e52-4698-b8d3-9126658ab2a6

则

mqttClientId: appkeyYoW23tX4aA3BJG6Q|timestamp1647968584000|noise123
mqttUserName: YoW23tX4aA3BJG6Q
mqttPassword: f84fb4bbfa93d1c06f8ede9bc1bf33b16fa6811

6.2.2 Topic定义

物模型通讯相关

通知类型	Topic
设备属性上报通知	{appkey}_thing/{productKey}/basicData
设备事件上报通知	{appkey}_thing/{productKey}/event/
设备服务返回值通知	{appkey}_thing/{productKey}/serviceResponse

设备管理相关

通知类型	Topic
设备状态变化通知	{appkey}_thing/{productKey}/networkStatus
设备生命周期变更通知	{appkey}_thing/{productKey}/deviceLifecycle/
设备影子变更通知	{appkey}_thing/{productKey}/deviceShadow/change

产品管理相关

通知类型	Topic
物模型生命周期变更通知	{appkey}_thing/{productKey}/modelLifecycle/

告警中心

通知类型	Topic
告警中心告警通知	iotpaas/{appkey}/alarmCenter

6.2.3 变量说明

变量	说明
	应用 AppKey，由基础服务新增应用后获取。
	应用秘钥
	毫秒值时间戳
	随机数
	产品 key 如：79b69gtW085
	事件类型 information: 信息 alarm: 告警 fault: 故障
	变更类型 add: 新增 update: 修改 delete: 删除

6.2.4 消息体定义

与 AMQP 消息体定义一致，详见 6.1.3

IoT 应用侧 API 文档 v1.0 ​

1. 关于IoT ​

2. 应用接入流程 ​

3. 配置物模型 ​

3.1 物模型概述 ​

3.1.1 物模型 ​

3.1.2 功能说明 ​

3.1.3 使用说明 ​

3.2 TSL概述 ​

3.2.1 物模型TSL字段说明 ​

3.2.2 物模型TSL示例 ​

3.3 物模型支持的数据类型 ​

4. 云端通用开发指南 ​

4.1 云端OpenApi通用鉴权机制 ​

4.2 JAVA示例代码 ​

4.3 公共参数 ​

4.4 公共请求参数 ​

4.5 错误码规范 ​

4.5.1 客户端错误码 ​

4.5.2 系统错误码 ​

4.5.3 业务错误码 ​

5. 云端IOTAPI ​

5.1 设备管理 ​

5.1.1 API列表 ​

5.1.2 注册设备 ​

5.1.3 查询设备信息 ​

5.1.4 删除设备 ​

5.1.5 批量获取设备在线状态 ​

5.1.6 批量激活设备 ​

5.1.7 批量解除设备激活 ​

5.1.8 获取网关子设备列表 ​

5.1.9 增加网关设备拓扑 ​

5.1.10 移除网关设备拓扑 ​

5.1.11 查询产品设备列表 ​

5.1.12 查询指定条件设备列表 ​

5.1.13 获取设备运行状态 ​

5.1.14 更新设备数据 ​

5.1.15 查询子设备绑定网关 ​

5.1.16 查询设备动参 ​

5.1.17 更新设备动参 ​

5.1.18 查询设备标签 ​

5.1.19 更新设备标签 ​

5.1.20 删除设备标签 ​

5.1.21 根据标签查询设备 ​

5.1.22 批量添加设备 ​

5.1.23 批量修改设备名称 ​

5.1.24 批量删除设备 ​

5.1.25 获取设备列表 ​

5.1.26 通过标准品（SP）key获取产品列表 ​

5.2 产品管理 ​

5.2.1 API列表 ​

5.2.2 查询产品详细信息 ​

5.2.3 查询分组设备列表 ​

5.2.4 创建产品 ​

5.2.5 更新产品 ​

5.2.6 删除产品 ​

5.2.7 创建&更新产品标签 ​

5.2.8 删除产品标签 ​

5.2.9 查询产品标签 ​

5.2.10 查询产品详细信息 ​

5.3 物模型使用 ​

5.3.1 API列表 ​

5.3.2 设置设备属性 ​

5.3.3 调用设备指定服务 ​

5.3.4 查询设备属性 ​

5.3.5 批量查询设备属性 ​

5.3.6 查询设备影子 ​

5.3.7 更新设备影子 ​

5.3.8 获取设备事件上报记录 ​

5.3.9 获取设备最新事件记录 ​

5.3.10 获取设备属性上报记录 ​

5.3.11 查询设备事件上报记录 ​

5.4 物模型管理 ​

5.4.1 查询产品物模型 ​

5.5 OTA升级 ​

5.5.1 获取当前升级任务信息 ​

5.5.2 升级设备 ​

5.6 设备日志 ​

5.6.1 触发设备日志上传 ​

5.6.2 查询设备日志 ​

IoT 应用侧 API 文档 v1.0

1. 关于IoT

2. 应用接入流程

3. 配置物模型

3.1 物模型概述

3.1.1 物模型

3.1.2 功能说明

3.1.3 使用说明

3.2 TSL概述

3.2.1 物模型TSL字段说明

3.2.2 物模型TSL示例

3.3 物模型支持的数据类型

4. 云端通用开发指南

4.1 云端OpenApi通用鉴权机制

4.2 JAVA示例代码

4.3 公共参数

4.4 公共请求参数

4.5 错误码规范

4.5.1 客户端错误码

4.5.2 系统错误码

4.5.3 业务错误码

5. 云端IOTAPI

5.1 设备管理

5.1.1 API列表

5.1.2 注册设备

5.1.3 查询设备信息

5.1.4 删除设备

5.1.5 批量获取设备在线状态

5.1.6 批量激活设备

5.1.7 批量解除设备激活

5.1.8 获取网关子设备列表

5.1.9 增加网关设备拓扑

5.1.10 移除网关设备拓扑

5.1.11 查询产品设备列表

5.1.12 查询指定条件设备列表

5.1.13 获取设备运行状态

5.1.14 更新设备数据

5.1.15 查询子设备绑定网关

5.1.16 查询设备动参

5.1.17 更新设备动参

5.1.18 查询设备标签

5.1.19 更新设备标签

5.1.20 删除设备标签

5.1.21 根据标签查询设备

5.1.22 批量添加设备

5.1.23 批量修改设备名称

5.1.24 批量删除设备

5.1.25 获取设备列表

5.1.26 通过标准品（SP）key获取产品列表

5.2 产品管理

5.2.1 API列表

5.2.2 查询产品详细信息

5.2.3 查询分组设备列表

5.2.4 创建产品

5.2.5 更新产品

5.2.6 删除产品

5.2.7 创建&更新产品标签

5.2.8 删除产品标签

5.2.9 查询产品标签

5.2.10 查询产品详细信息

5.3 物模型使用

5.3.1 API列表

5.3.2 设置设备属性

5.3.3 调用设备指定服务

5.3.4 查询设备属性

5.3.5 批量查询设备属性

5.3.6 查询设备影子

5.3.7 更新设备影子

5.3.8 获取设备事件上报记录

5.3.9 获取设备最新事件记录

5.3.10 获取设备属性上报记录

5.3.11 查询设备事件上报记录

5.4 物模型管理

5.4.1 查询产品物模型

5.5 OTA升级

5.5.1 获取当前升级任务信息

5.5.2 升级设备

5.6 设备日志

5.6.1 触发设备日志上传

5.6.2 查询设备日志