# 2.5 用量查询

## 功能说明

用量查询功能允许你配置自定义脚本，实时查询供应商的剩余额度、已用量等信息。

**使用场景**：
- 查看 API 账户剩余余额
- 监控套餐使用情况
- 多套餐额度汇总显示

## 打开配置

1. 鼠标悬停在供应商卡片上，显示操作按钮
2. 点击「用量查询」按钮（📊 图标）
3. 打开用量查询配置面板

## 启用用量查询

在配置面板顶部，开启「启用用量查询」开关。

## 预设模板

CC Switch 提供三种预设模板：

### 自定义模板

完全自定义请求和提取逻辑，适用于特殊 API 格式。

### 通用模板

适用于大多数标准 API 格式的供应商：

```javascript
({
  request: {
    url: "{{baseUrl}}/user/balance",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}",
      "User-Agent": "cc-switch/1.0"
    }
  },
  extractor: function(response) {
    return {
      isValid: response.is_active || true,
      remaining: response.balance,
      unit: "USD"
    };
  }
})
```

**配置参数**：
| 参数 | 说明 |
|------|------|
| API Key | 用于认证的密钥（可选，留空则使用供应商配置的 Key） |
| Base URL | API 基础地址（可选，留空则使用供应商端点） |

### New API 模板

专为 New API 类型的中转服务设计：

```javascript
({
  request: {
    url: "{{baseUrl}}/api/user/self",
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer {{accessToken}}",
      "New-Api-User": "{{userId}}"
    },
  },
  extractor: function (response) {
    if (response.success && response.data) {
      return {
        planName: response.data.group || "默认套餐",
        remaining: response.data.quota / 500000,
        used: response.data.used_quota / 500000,
        total: (response.data.quota + response.data.used_quota) / 500000,
        unit: "USD",
      };
    }
    return {
      isValid: false,
      invalidMessage: response.message || "查询失败"
    };
  },
})
```

**配置参数**：
| 参数 | 说明 |
|------|------|
| Base URL | New API 服务地址 |
| Access Token | 访问令牌 |
| User ID | 用户 ID |

## 通用配置

### 超时时间

请求超时时间（秒），默认 10 秒。

### 自动查询间隔

自动刷新用量数据的间隔（分钟）：
- 设为 `0` 表示禁用自动查询
- 范围：0-1440 分钟（最长 24 小时）
- 仅当供应商处于「当前启用」状态时生效

## 提取器返回格式

提取器函数需要返回包含以下字段的对象：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `isValid` | boolean | 否 | 账户是否有效，默认 true |
| `invalidMessage` | string | 否 | 无效时的提示信息 |
| `remaining` | number | 是 | 剩余额度 |
| `unit` | string | 是 | 单位（如 USD、CNY、次） |
| `planName` | string | 否 | 套餐名称（支持多套餐） |
| `total` | number | 否 | 总额度 |
| `used` | number | 否 | 已使用额度 |
| `extra` | object | 否 | 额外信息 |

## 测试脚本

配置完成后，点击「测试脚本」按钮验证：

1. 发送请求到配置的 URL
2. 执行提取器函数
3. 显示返回结果或错误信息

## 显示效果

配置成功后，供应商卡片上会显示：

- **单套餐**：直接显示剩余额度
- **多套餐**：显示套餐数量，点击展开查看详情

## 变量占位符

脚本中可使用以下占位符，运行时自动替换：

| 占位符 | 说明 |
|--------|------|
| `{{apiKey}}` | 配置的 API Key |
| `{{baseUrl}}` | 配置的 Base URL |
| `{{accessToken}}` | 配置的 Access Token（New API） |
| `{{userId}}` | 配置的 User ID（New API） |

## 常见供应商配置示例

### 故障排除

### 查询失败

**检查**：
1. API Key 是否正确
2. Base URL 是否正确
3. 网络是否可访问
4. 超时时间是否足够

### 返回数据为空

**检查**：
1. 提取器函数是否有 `return` 语句
2. 响应数据结构是否与提取器匹配
3. 使用「测试脚本」查看原始响应

### 格式化失败

脚本语法错误时，点击「格式化」按钮会提示错误位置。

## 注意事项

- 用量查询会消耗少量 API 请求配额
- 建议设置合理的自动查询间隔，避免频繁请求
- 敏感信息（API Key、Token）会安全存储在本地