设备管理

更新时间:2022-06-27 09:26:58下载pdf

您可以使用以下 API 查询您的设备信息。

请求方式 API 描述
PUT /v1.0/illumination/device/{deviceSaasId}/name 修改设备名称
GET /v1.0/illumination/devices 获取设备信息列表
GET /v1.0/illumination/devices/{deviceSaasId}/detail 设备 ID 查询单个设备详情
GET /v1.0/illumination/devices/unassignedRoom 未分区设备列表
GET /v1.0/illumination/devices/roomstate/{roomId} 查询房间设备状态
POST /v1.0/illumination/devices/{deviceId}/resetGateway 设备删除
POST /v1.0/illumination/device/relations/save 设备空间划分

修改设备名称

功能描述

修改设备名称

接口地址

PUT /v1.0/illumination/device/{deviceSaasId}/name

请求参数

参数名 类型 参数类型 说明 是否必需
deviceSaasId String url 设备ID true
name String url 设备名称 true

返回参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果

result参数说明

ResponseVO{}

请求示例

{
  "name": "设备名称",
  "deviceSaasId": "设备ID"
}

响应示例

ResponseVO{}

获取设备信息列表

功能描述

根据条件分页获取设备信息列表。

接口地址

GET /v1.0/illumination/devices

请求参数

参数名 类型 参数类型 说明 是否必需
projectId String body 项目 ID
roomId String body 房间 ID
roomType int body 房间类型
page int body 页码参数,最小为 1
pageSize int body 每页记录数量,最大为 10000
deviceName String body 设备名称模糊查询
deviceStatus String[] body 设备状态
  • EXPIRING
  • EXCEPTION
  • ONLINE
  • OFFLINE

返回参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13 位
result Object 返回结果

result参数说明

{
  "total": "int",
  "list": [
    {
      "deviceSaasId": "String //设备商照唯一 ID",
      "deviceId": "String //设备ID,和硬件设备一一对应,由于设备重新绑定点位,导致在这里不唯一",
      "deviceName": "String //设备名称",
      "deviceType": "String //设备类型,详见 DeviceTypeEnum",
      "deviceTypeValue": "int //设备类型,详见 DeviceTypeEnum",
      "topCategory": "String //产品所属大级分类。      详见 ProductCategoryEnum 的类型说明",
      "devicePower": "double //设备功率",
      "deviceStatus": "设备状态 NORMAL/OFFLINE/EXPIRING/EXCEPTION",
      "installTime": "long //设备安装时间",
      "activeTime": "long //设备活跃时间",
      "productId": "String //设备品类(产品) ID",
      "roomId": "String //设备所属房间 ID",
      "roomName": "String //设备所属房间名称",
      "ownerId": "String //所属设备家庭组 ID",
      "properties": [
        {
          "dpId": "Integer //DP ID",
          "dpCode": "String //DP 点代码",
          "dpName": "String //DP 点名称",
          "dpValueStd": "String //DP 当前值",
          "property": {
            "range": "String[] //描述属性值的取值范围"
          },
          "propertyDetail": {},
          "mode": "String //mode 模式 例如 ro,rw  1.4.3 新增",
          "dpFrom": "String"
        }
      ],
      "masterGroupJoinStatus": "int //主群组加入状态,0 表示未加入,1 表示已加入,2 未加入群组的非照明设备",
      "currentBrightness": "int //设备所属房间的亮度阈值",
      "supportGroup": "boolean //是否支持群组",
      "switchStatus": "boolean //开关状态",
      "switchDpCode": "String //开关 dpCode",
      "colourValue": "String //颜色值",
      "brightPercentValue": "String //亮度百分比值",
      "iconUrl": "String //设备图标"
    }
  ]
}

请求示例

{
  "pageSize": "每页记录数量",
  "page": "页码参数",
  "projectId": "项目 ID",
  "roomId": "房间 ID",
  "roomType": "房间类型",
  "deviceStatus": "设备状态"
}

响应示例

{
  "total": "int",
  "list": [
    {
      "deviceSaasId": "设备商照唯一 ID",
      "deviceId": "设备 ID,和硬件设备一一对应,由于设备重新绑定点位,导致在这里不唯一",
      "deviceName": "设备名称",
      "deviceType": "设备类型,详见 DeviceTypeEnum",
      "deviceTypeValue": "设备类型,详见 DeviceTypeEnum",
      "topCategory": "产品所属大级分类。      详见 ProductCategoryEnum 的类型说明",
      "devicePower": "设备功率",
      "deviceStatus": "设备状态 NORMAL/OFFLINE/EXPIRING/EXCEPTION",
      "installTime": "设备安装时间",
      "activeTime": "设备活跃时间",
      "productId": "设备品类(产品) ID",
      "roomId": "设备所属房间 ID",
      "roomName": "设备所属房间名称",
      "pointId": "设备所在点位 ID",
      "ownerId": "所属设备家庭组 ID",
      "properties": [
        {
          "dpId": "DP ID",
          "dpCode": "DP 点代码",
          "dpName": "DP 点名称",
          "dpValueStd": "DP 当前值",
          "property": {
            "range": "描述属性值的取值范围"
          },
          "propertyDetail": {},
          "mode": "mode 模式 例如 ro,rw  1.4.3 新增",
          "dpFrom": "String"
        }
      ],
      "masterGroupJoinStatus": "主群组加入状态,0 表示未加入,1 表示已加入,2 未加入群组的非照明设备",
      "currentBrightness": "设备所属房间的亮度阈值",
      "supportGroup": "是否支持群组",
      "switchStatus": "开关状态",
      "switchDpCode": "开关 dpCode",
      "colourValue": "颜色值",
      "brightPercentValue": "亮度百分比值",
      "iconUrl": "设备图标地址",
      "pointDeviceType": "点位图上设备类型",
      "switchCount": "int",
      "dpFrom": "String"
    }
  ]
}

获取单个设备的详细信息

功能描述

根据 deviceSaasId 获取单个设备的详细信息。

接口地址

GET /v1.0/illumination/devices/{deviceSaasId}/detail

请求参数

参数名 类型 参数类型 说明 是否必需
deviceSaasId String url 设备 ID

返回参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13 位
result Object 返回结果

result 参数说明

同获取设备信息列表接口。

请求示例

{
  "deviceSaasId": "设备 ID"
}

响应示例

同获取设备信息列表接口。

未分区设备列表

功能描述

查询项目下未分配到空间的设备列表。

接口地址

GET /v1.0/illumination/devices/unassignedRoom

请求参数

参数名 类型 参数类型 说明 是否必需
page int body 页数,最小为 1
pageSize int body 数量,最大为 10000
projectId String body 项目 ID
deviceStatus String[] body 设备状态
  • EXPIRING
  • EXCEPTION
  • ONLINE
  • OFFLINE
deviceTypes int[] body 设备类型
  • -1:其他
  • 0:智能灯
  • 1:网关设备
  • 2:非智能灯
  • 3:开关设备
  • 4:传感器设备

返回参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果

result 参数说明

同获取设备信息列表接口。

请求示例

{
  "pageSize": "数量",
  "page": "页数",
  "projectId": "项目 ID",
  "topCategories": "设备状态筛选列表 Code (电工 dgzm, 照明 zm, 小家电 xjd, 安防传感类 jjaf, 网关中控 wgzk, 其他类 qt)",
  "deviceName": "设备名称",
  "roomId": "房间 ID",
  "deviceStatus": "设备状态筛选列表"
}

响应示例

同获取设备信息列表接口。

查询房间设备状态

功能描述

查询房间设备状态,V1.4.3 新增功能。

接口地址

GET /v1.0/illumination/devices/roomstate/{roomId}

请求参数

参数名 类型 参数类型 说明 是否必需
roomId String url 房间 ID

返回参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13 位
result Object 返回结果

result 参数说明

{
  "properties": [
    {
      "dpCode": "String //DP 点代码",
      "dpName": "String //DP 点名称",
      "dpValueStd": "String //DP 当前值",
      "property": {
        "range": "String[] //描述属性值的取值范围"
      },
      "propertyDetail": {},
      "mode": "String //mode 模式 例如 ro,rw  1.4.3新增",
      "dpFrom": "String"
    }
  ],
  "count": {
    "total": "long //总设备数量",
    "online": "long //在线设备数量",
    "offline": "long //离线设备数量",
    "expiring": "long //更换报警设备数量",
    "exception": "long //DP 报警设备数量"
  }
}

请求示例

{
  "roomId": "房间 ID"
}

响应示例

{
  "properties": [
    {
      "dpCode": "DP 点代码",
      "dpName": "DP 点名称",
      "dpValueStd": "DP 当前值",
      "property": {
        "range": "描述属性值的取值范围"
      },
      "propertyDetail": {},
      "mode": "mode 模式 例如 ro,rw  1.4.3新增",
      "dpFrom": "String"
    }
  ],
  "count": {
    "total": "总设备数量",
    "online": "在线设备数量",
    "offline": "离线设备数量",
    "expiring": "更换报警设备数量",
    "exception": "DP 报警设备数量"
  }
}

设备删除

功能描述

删除指定设备 ID 的设备。

接口地址

POST /v1.0/illumination/devices/{deviceId}/resetGateway

请求参数

参数名 类型 参数类型 说明 是否必需
deviceId String url 设备 ID
projectId String body 项目 ID

返回参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果

result参数说明

{
  "action": "设备删除成功",
  "message": "SUCCESS"
}

请求示例

{
  "projectId": "项目 ID"
}

响应示例

{
  "action": "设备删除成功",
  "message": "SUCCESS"
}

设备空间划分

功能描述

将指定设备划分到指定空间。

接口地址

POST /v1.0/illumination/device/relations/save

请求参数

参数名 类型 参数类型 说明 是否必需
projectId String body 项目 ID
roomId String body 空间 ID,未分区空间 ID 为 0
deviceIds List body 设备 ID 列表

返回参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果

result参数说明

{
  "expiredSeconds": "过期时间, 单位秒, 这个时间之后该任务就会过期",
  "taskId": "任务 ID"
}

请求示例

{
  "deviceIds": "设备 ID 列表",
  "projectId": "项目 ID",
  "roomId": "空间 ID, 未分区空间 ID 为 0"
}

响应示例

{
  "expiredSeconds": "过期时间, 单位秒, 这个时间之后该任务就会过期",
  "taskId": "任务 ID"
}

错误码

以下为该接口常见的业务异常,更多的异常错误,请参见全局错误码

错误码 说明
500 系统错误