b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
142 lines
3.9 KiB
Markdown
142 lines
3.9 KiB
Markdown
<!-- mipuyun-api-doc: device-list -->
|
||
# device/list - 设备列表
|
||
|
||
## 概述
|
||
|
||
设备列表API用于查询当前客户的所有设备信息，包括设备状态、绑定的VCC卡、任务状态等。
|
||
|
||
### 用户使用场景
|
||
|
||
本接口用于：
|
||
- 查看所有可用设备及其在线状态
|
||
- 检查设备的VCC卡绑定情况
|
||
- 查看设备的任务处理状态
|
||
|
||
## 请求说明
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| **请求地址** | `https://${endpoint}/device/list` |
|
||
| **请求方法** | GET |
|
||
| **注意事项** | 无需请求体，从Header中获取clientCode |
|
||
|
||
### Header 参数
|
||
|
||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||
|----------|------|----------|--------|------|
|
||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
|
||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
|
||
|
||
## 返回参数
|
||
|
||
成功时返回设备信息列表：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"deviceId": "device-001",
|
||
"status": "ONLINE",
|
||
"vccCardNumber": "424242******4242",
|
||
"bindingVccCardNumber": "555555******5555",
|
||
"lastHeartbeatTime": 1704140800000,
|
||
"taskStatus": "PROCESSING",
|
||
"processingTask": {
|
||
"taskId": "task-123",
|
||
"taskType": "BIND_VCC",
|
||
"status": "PROCESSING",
|
||
"createTime": "2025-01-15T10:30:00Z",
|
||
"updateTime": "2025-01-15T10:35:00Z",
|
||
"deviceId": "device-001"
|
||
},
|
||
"pendingTasks": []
|
||
},
|
||
{
|
||
"deviceId": "device-002",
|
||
"status": "OFFLINE",
|
||
"vccCardNumber": "378222******2222",
|
||
"bindingVccCardNumber": null,
|
||
"lastHeartbeatTime": 1704130000000,
|
||
"taskStatus": "IDLE",
|
||
"processingTask": null,
|
||
"pendingTasks": [
|
||
{
|
||
"taskId": "task-124",
|
||
"taskType": "UNBIND_VCC",
|
||
"status": "PENDING",
|
||
"createTime": "2025-01-15T11:00:00Z",
|
||
"updateTime": "2025-01-15T11:00:00Z",
|
||
"deviceId": "device-002"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
| 参数名称 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| deviceId | String | 设备编号 |
|
||
| status | String | 设备状态：ONLINE=在线，OFFLINE=离线 |
|
||
| vccCardNumber | String | 当前绑定的VCC卡号（脱敏显示） |
|
||
| bindingVccCardNumber | String | 正在绑定的VCC卡号（脱敏显示，绑定任务进行中时存在） |
|
||
| lastHeartbeatTime | Long | 最后心跳时间（时间戳毫秒） |
|
||
| taskStatus | String | 任务状态：IDLE=空闲，PROCESSING=处理中，PENDING=有等待任务 |
|
||
| processingTask | Object | 正在执行的任务信息 |
|
||
| pendingTasks | Array | 等待队列中的任务列表 |
|
||
|
||
### TaskInfo 任务信息
|
||
|
||
| 参数名称 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| taskId | String | 任务ID |
|
||
| taskType | String | 任务类型：BIND_VCC=绑定VCC卡，UNBIND_VCC=解绑VCC卡，PAYMENT=支付 |
|
||
| status | String | 任务状态：PENDING=等待中，PROCESSING=处理中，COMPLETED=已完成，FAILED=失败 |
|
||
| createTime | String | 创建时间（ISO 8601格式） |
|
||
| updateTime | String | 更新时间（ISO 8601格式） |
|
||
| deviceId | String | 设备ID |
|
||
|
||
## 业务案例
|
||
|
||
### 查询所有设备状态
|
||
|
||
### 请求
|
||
|
||
```bash
|
||
curl -X GET "https://${endpoint}/device/list" \
|
||
-H "client-key: your_key" \
|
||
-H "client-secret: your_secret"
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
[
|
||
{
|
||
"deviceId": "device-001",
|
||
"status": "ONLINE",
|
||
"vccCardNumber": "424242******4242",
|
||
"bindingVccCardNumber": null,
|
||
"lastHeartbeatTime": 1704140800000,
|
||
"taskStatus": "IDLE",
|
||
"processingTask": null,
|
||
"pendingTasks": []
|
||
}
|
||
]
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 设备状态ONLINE和OFFLINE的区别是什么？
|
||
|
||
- **ONLINE**：设备在线，可以接收和处理任务
|
||
- **OFFLINE**：设备离线，无法处理任务
|
||
|
||
### taskStatus有几种状态？
|
||
|
||
- **IDLE**：设备空闲，没有正在处理的任务
|
||
- **PROCESSING**：设备正在执行任务
|
||
- **PENDING**：设备有待处理的任务队列
|
||
|
||
### VCC卡号为什么要脱敏显示？
|
||
|
||
为了保护支付安全，VCC卡号只显示前6位和后4位，中间用*替换。
|