cc-switch/docs/user-manual/zh/2-providers/2.5-usage-query.md

2.5 用量查询

功能说明

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

使用场景：

• 查看 API 账户剩余余额
• 监控套餐使用情况
• 多套餐额度汇总显示

打开配置

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

启用用量查询

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

预设模板

CC Switch 提供三种预设模板：

自定义模板

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

通用模板

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

({
  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 类型的中转服务设计：

({
  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）会安全存储在本地