---
name: "getDeviceData"
mode: "api"
versionRequirements:
  - { name: "@tuya-miniapp/cloud-api", version: "1.3.0" }
---

## getDeviceData

> [VERSION] @tuya-miniapp/cloud-api >= 1.3.0

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

### 描述

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

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `params` | `GetDeviceDataParams` | 是 | 请求参数 |

### 返回值

类型: `Promise<GetDeviceDataResult>`

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

### 引用对象

##### `interface` GetDeviceDataParams

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `devId` | `string` | 设备 ID |
| `indicatorCode` | `"IndicatorCode.EleUsage" \\| "IndicatorCode.EleCost"` | 指标编码，推荐使用 `IndicatorCode` 枚举 |
| `dateType` | `"DateType.Hour" \\| "DateType.Day" \\| "DateType.Month"` | 时间维度，推荐使用 `DateType` 枚举 |
| `beginDate` | `string` | 开始时间，格式与 `dateType` 对应 |
| `endDate` | `string` | 结束时间，格式与 `dateType` 对应 |
| `aggregationType` | `"SUM" \| "AVG" \| "MAX"` | 聚合方式，默认为 `SUM`（求和） |
| `options` | `string` | 扩展参数，JSON 字符串，一般无需传入 |

##### `interface` GetDeviceDataResult

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `total` | `number` | 区间汇总值 |
| `unit` | `string` | 指标单位，如 `kWh`、`元` |
| `list` | `DeviceDataItem[]` | 分段数据列表，无数据时对应 `value` 为 `0` |

##### `enum` IndicatorCode

| 枚举值 | 实际值 | 描述 |
| --- | --- | --- |
| `IndicatorCode.EleUsage` | `ele_usage` | 用电量 |
| `IndicatorCode.EleCost` | `ele_cost` | 电费 |

##### `enum` DateType

| 枚举值 | 实际值 | 描述 |
| --- | --- | --- |
| `DateType.Hour` | `hour` | 小时维度，日期格式为 `YYYYMMDDHH`，如 `2026010108` |
| `DateType.Day` | `day` | 天维度，日期格式为 `YYYYMMDD`，如 `20260101` |
| `DateType.Month` | `month` | 月维度，日期格式为 `YYYYMM`，如 `202601` |

##### `type` DeviceDataItem

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `date` | `string` | 时间点，格式与请求的 `dateType` 保持一致 |
| `value` | `number` | 该时间点对应的指标数值 |


### 示例代码

#### 请求示例

```javascript
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);
  });
```

#### 返回示例

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


### 常见问题

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

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