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

## getDeviceConsumeBudget

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

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

### 描述

查询设备电量预算列表。仅返回 energyAction 为 consume 的预算项，可用于在 UI 层展示预算进度或预算阈值告警。

### 参数

`Params`

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

### 返回值

类型: `Promise<GetDeviceConsumeBudgetResult>`

电量预算列表（energyAction 固定为 consume），每项含 dateType（预算维度：day/week/month）、budget（预算值，单位 kWh）、entityId（设备 ID）等字段；未设置某维度时该维度不在列表中

### 引用对象

##### `interface` GetDeviceConsumeBudgetParams

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `devId` | `string` | 设备 ID |

##### `type` GetDeviceConsumeBudgetResult

`getDeviceConsumeBudget` 返回值，电量预算列表

```typescript
export type GetDeviceConsumeBudgetResult = DeviceBudget[];
```

##### `interface` DeviceBudget

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `bizId` | `string` | 业务 ID |
| `budget` | `string` | 预算值，单位视 `energyAction` 而定（kWh 或货币） |
| `dateType` | `"BudgetDataType.Day" \\| "BudgetDataType.Week" \\| "BudgetDataType.Month"` | 预算时间维度 |
| `energyAction` | `"EnergyAction.Cost" \\| "EnergyAction.Consume"` | 能源动作类型（`consume` 或 `cost`） |
| `entityId` | `string` | 实体 ID（即设备 ID） |
| `entityType` | `string` | 实体类型 |
| `projectId` | `string` | 项目 ID |
| `projectType` | `string` | 项目类型 |

##### `enum` BudgetDataType

| 枚举值 | 实际值 | 描述 |
| --- | --- | --- |
| `BudgetDataType.Day` | `day` | 按天 |
| `BudgetDataType.Week` | `week` | 按周 |
| `BudgetDataType.Month` | `month` | 按月 |

##### `enum` EnergyAction

| 枚举值 | 实际值 | 描述 |
| --- | --- | --- |
| `EnergyAction.Cost` | `cost` | 电费 |
| `EnergyAction.Consume` | `consume` | 用电量 |


### 示例代码

#### 请求示例

```javascript
import { getDeviceConsumeBudget } from '@tuya-miniapp/cloud-api';

getDeviceConsumeBudget({ devId: 'vdevo123' })
  .then(result => {
    result.forEach(item => {
      console.log(`${item.dateType} 电量预算: ${item.budget} kWh`);
    });
  })
  .catch(error => {
    console.error('查询电量预算失败:', error);
  });
```

#### 返回示例

```json
[
  {
    "dateType": "day",
    "budget": "5",
    "energyAction": "consume",
    "bizId": "biz_001",
    "entityId": "vdevo123",
    "entityType": "device",
    "projectId": "proj_001",
    "projectType": "smartenergy"
  },
  {
    "dateType": "month",
    "budget": "80",
    "energyAction": "consume",
    "bizId": "biz_002",
    "entityId": "vdevo123",
    "entityType": "device",
    "projectId": "proj_001",
    "projectType": "smartenergy"
  }
]
```


### 常见问题

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

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