能耗管理

本文介绍能耗管理相关 API。

API 列表

请求方式	API	描述
GET	/v1.0/illumination/space/energy/query	查询空间能耗
POST	/v1.0/cloud/illume/open/energy/device	查询设备能耗

查询空间能耗

功能描述

查询空间下某个时间段内的能耗数据。

• 天-同比：展示当天与上周同一天的能源数据对比。

• 月-同比：展示本月与去年同一月的能源数据对比。

• 天-环比：展示当天与昨天的能源数据对比。

• 月-环比：展示本月与上月的能源数据对比。

• 年-环比：展示本年与上一年的能源数据对比。

接口地址

GET /v1.0/illumination/space/energy/query

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
roomId	String	body	空间 ID	false
targetType	int	body	查询类型 1：日 2：月 3：年	true
startTime	long	body	开始时间	true
endTime	long	body	结束时间	true

参数说明

• targetType 为 1 时，时间戳必须为该天 0 点到次日 0 点，中间只能相差一天。
• targetType 为 2 时，时间戳必须相差 2 到 31 天，即最小为该日 0 点到后天 0 点，最大为本月 1 日 0 点到次月 1 日 0 点（大月）。
• targetType 为 3 时，时间戳必须相差 12 个月内，即最小为 1 月到 2 月，最大为 1 月到次年 1 月（与日和时无关）。

返回参数

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

result 参数说明

{
  "totalEnergy": "double //累计能耗",
  "averageEnergy": "double //平均能耗",
  "tbValue": "double //同期差值",
  "hbValue": "double //环期差值",
  "tb": "double //当前同比",
  "hb": "double //当前环比",
  "data": [
    {
      "sort": "int //排序字段",
      "time": "long //时间戳",
      "totalEnergy": "double //总能耗值",
      "data": [
        {
          "purposeCode": "int //用途",
          "i18nName": "String //多语言名称",
          "energy": "double //能耗值"
        }
      ]
    }
  ]
}

请求示例

{
  "targetType": "查询类型，1 表示日，2 表示月，3 表示年",
  "startTime": "开始时间",
  "endTime": "结束时间",
  "projectId": "项目 ID",
  "roomId": "空间 ID"
}

响应示例

{
  "totalEnergy": "累计能耗",
  "averageEnergy": "平均能耗",
  "tbValue": "同期差值",
  "hbValue": "环期差值",
  "tb": "当前同比",
  "hb": "当前环比",
  "data": [
    {
      "sort": "排序字段",
      "time": "时间戳",
      "totalEnergy": "总能耗值",
      "data": [
        {
          "purposeCode": "用途",
          "i18nName": "多语言名称",
          "energy": "能耗值"
        }
      ]
    }
  ]
}

查询设备能耗

功能描述

支持批量查询多个设备的能耗数据。

接口地址

POST /v1.0/cloud/illume/open/energy/device

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
deviceIds	String[]	body	设备 ID 列表	true
period	String	body	周期 day：某天 week：本周 month：本月 year：本年 custom_day：自定义某天
energyType	int	body	能耗类型 electricity：电 water：水 gas：气	true
startTime	long	body	开始时间 day、week 和 custom_day 的格式：yyyyMMdd month 和 year 格式：yyyyMM	true
endTime	long	body	结束时间 day、week 和 custom_day 的格式：yyyyMMdd month 和 year 格式：yyyyMM	true

返回参数

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

result 参数说明

{
  "totalEnergy": "String //累计能耗",
  "averageEnergy": "String //平均能耗",
  "energyDetail": [
    {
      "energy": "String //能耗值",
      "theoryEnergy": "String //理论能耗值",
      "theoryRadio": "String //理论能耗比",
      "time": "String //日期"
    }
  ]
}

请求示例

{
  "projectId": "1793201629403611***",
  "deviceIds": [
    "6cc4908944f7e67dadg***"
  ],
  "period": "day",
  "energyType": "electricity",
  "startTime": "20240724",
  "endTime": "20240724"
}

响应示例

{
  "result": {
    "averageEnergy": "0.002",
    "energyDetail": [
      {
        "energy": "0.002",
        "theoryEnergy": "0.012",
        "theoryRadio": "0.857",
        "time": 2024072400
      },
      {
        "energy": "0.000",
        "theoryEnergy": "--",
        "theoryRadio": "--",
        "time": 2024072416
      }
    ],
    "totalEnergy": "0.028"
  },
  "success": true,
  "t": 1721807661231,
  "tid": "ef604ae2499111efb454526982c4e3fa"
}

错误码

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

错误码	说明
500	系统错误