本页目录
常见问题为什么调用云能力会出现失败的情况？

getDeviceData(params: GetDeviceDataParams)

版本要求:
@tuya-miniapp/cloud-api≥1.3.0

描述

按时间范围查询设备能源指标数据。支持按小时、天、月维度聚合，可指定聚合方式（求和、均值、最大值）。返回数据包含汇总值、单位及分段明细列表。

参数

参数类型必填说明
是请求参数

返回值

类型：Promise<GetDeviceDataResult>
包含 total（区间汇总值）、unit（指标单位，如 kWh）、list（分段数据，每项含 date 和 value，无数据时 value 为 0）的对象

引用对象

interfaceGetDeviceDataResult
属性类型描述
totalnumber区间汇总值
unitstring指标单位，如 `kWh`、`元`
分段数据列表，无数据时对应 `value` 为 `0`
enumIndicatorCode
枚举值实际值描述
IndicatorCode.EleUsageele_usage用电量
IndicatorCode.EleCostele_cost电费
enumDateType
枚举值实际值描述
DateType.Hourhour小时维度，日期格式为 `YYYYMMDDHH`，如 `2026010108`
DateType.Dayday天维度，日期格式为 `YYYYMMDD`，如 `20260101`
DateType.Monthmonth月维度，日期格式为 `YYYYMM`，如 `202601`

合法值

IndicatorCode
值说明最低版本
ele_usage用电量-
ele_cost电费-
DateType
值说明最低版本
hour小时维度，日期格式为 `YYYYMMDDHH`，如 `2026010108`-
day天维度，日期格式为 `YYYYMMDD`，如 `20260101`-
month月维度，日期格式为 `YYYYMM`，如 `202601`-
GetDeviceDataParams.aggregationType
值说明最低版本
SUM--
AVG--
MAX--

示例代码

请求示例

import { getDeviceData, IndicatorCode, DateType } from '@tuya-miniapp/cloud-api';

getDeviceData({
  devId: 'vdevo123',
  indicatorCode: IndicatorCode.EleUsage,
  dateType: DateType.Day,
  beginDate: '20260101',
  endDate: '20260131',
})
  .then(result => {
    console.log('能源数据汇总:', result.total, result.unit);
    result.list.forEach(item => {
      console.log(`${item.date}: ${item.value} ${result.unit}`);
    });
  })
  .catch(error => {
    console.error('查询能源数据失败:', error);
  });

返回示例

{
  "total": 31.2,
  "unit": "kWh",
  "list": [
    { "date": "20260101", "value": 1.2 },
    { "date": "20260102", "value": 0.8 },
    { "date": "20260103", "value": 1.5 }
  ]
}

常见问题

为什么调用云能力会出现失败的情况？

使用本接口前，请确保设备所属产品已在涂鸦 IoT 开发平台开启电量统计高级能力。未启用该能力的产品无法采集电量/电费数据，接口将返回空数据或报错。如需使用，请创建带有电量/电费统计功能的产品，并在产品详情中启用相应高级能力。同时，接口依赖云能力，需在小程序开发者平台开发设置 - 云能力进行授权配置。