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>
166 lines
4.3 KiB
Markdown
166 lines
4.3 KiB
Markdown
<!-- mipuyun-api-doc: device-task -->
|
||
# device/task/{taskId} - 查询任务
|
||
|
||
## 概述
|
||
|
||
任务查询API用于查询设备任务的执行状态和详情。通过绑定/解绑接口获取的任务ID，可以使用本接口查询任务进度。
|
||
|
||
### 用户使用场景
|
||
|
||
本接口用于：
|
||
- 查询VCC卡绑定任务的状态
|
||
- 查询VCC卡解绑任务的状态
|
||
- 查询支付任务的状态
|
||
- 获取任务的详细信息和设备状态
|
||
|
||
## 请求说明
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| **请求地址** | `https://${endpoint}/device/task/{taskId}` |
|
||
| **请求方法** | GET |
|
||
| **注意事项** | taskId从绑定/解绑接口返回中获取 |
|
||
|
||
### Header 参数
|
||
|
||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||
|----------|------|----------|--------|------|
|
||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
|
||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
|
||
|
||
### URL 参数
|
||
|
||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||
|----------|------|----------|--------|------|
|
||
| taskId | String | 是 | "task-bind-123456" | 任务ID，从绑定/解绑接口返回 |
|
||
|
||
## 返回参数
|
||
|
||
成功时返回任务详情：
|
||
|
||
```json
|
||
{
|
||
"deviceId": "device-001",
|
||
"deviceStatus": "ONLINE",
|
||
"task": {
|
||
"taskId": "task-bind-123456",
|
||
"taskType": "BIND_VCC",
|
||
"status": "PROCESSING",
|
||
"createTime": "2025-01-15T10:30:00Z",
|
||
"updateTime": "2025-01-15T10:35:00Z",
|
||
"deviceId": "device-001",
|
||
"orderId": null,
|
||
"creditCard": {
|
||
"cardNumber": "424242******4242",
|
||
"cvv": "***",
|
||
"expiryDate": "12/25"
|
||
},
|
||
"orderDetail": null
|
||
}
|
||
}
|
||
```
|
||
|
||
| 参数名称 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| deviceId | String | 执行任务的设备ID |
|
||
| deviceStatus | String | 设备状态：ONLINE=在线，OFFLINE=离线 |
|
||
| task | Object | 任务详细信息 |
|
||
|
||
### Task 任务信息
|
||
|
||
| 参数名称 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| 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 |
|
||
| orderId | String | 订单ID（仅PAYMENT类型任务） |
|
||
| creditCard | Object | 信用卡信息（仅BIND_VCC类型任务，脱敏显示） |
|
||
| orderDetail | String | 订单详情（仅PAYMENT类型任务） |
|
||
|
||
## 业务案例
|
||
|
||
### 查询绑定任务状态
|
||
|
||
### 请求
|
||
|
||
```bash
|
||
curl -X GET "https://${endpoint}/device/task/task-bind-123456" \
|
||
-H "client-key: your_key" \
|
||
-H "client-secret: your_secret"
|
||
```
|
||
|
||
### 响应 - 任务处理中
|
||
|
||
```json
|
||
{
|
||
"deviceId": "device-001",
|
||
"deviceStatus": "ONLINE",
|
||
"task": {
|
||
"taskId": "task-bind-123456",
|
||
"taskType": "BIND_VCC",
|
||
"status": "PROCESSING",
|
||
"createTime": "2025-01-15T10:30:00Z",
|
||
"updateTime": "2025-01-15T10:35:00Z",
|
||
"deviceId": "device-001",
|
||
"creditCard": {
|
||
"cardNumber": "424242******4242",
|
||
"cvv": "***",
|
||
"expiryDate": "12/25"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应 - 任务完成
|
||
|
||
```json
|
||
{
|
||
"deviceId": "device-001",
|
||
"deviceStatus": "ONLINE",
|
||
"task": {
|
||
"taskId": "task-bind-123456",
|
||
"taskType": "BIND_VCC",
|
||
"status": "COMPLETED",
|
||
"createTime": "2025-01-15T10:30:00Z",
|
||
"updateTime": "2025-01-15T10:36:00Z",
|
||
"deviceId": "device-001"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应 - 任务不存在
|
||
|
||
```json
|
||
{
|
||
"deviceId": null,
|
||
"deviceStatus": null,
|
||
"task": null
|
||
}
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 任务状态有哪几种？
|
||
|
||
- **PENDING**：任务在队列中等待执行
|
||
- **PROCESSING**：任务正在执行中
|
||
- **COMPLETED**：任务执行完成
|
||
- **FAILED**：任务执行失败
|
||
|
||
### 任务查询不到是什么原因？
|
||
|
||
- 任务ID错误
|
||
- 任务已完成且已被清理（根据系统配置，任务可能会在完成后一段时间被清理）
|
||
- 任务ID来自其他客户
|
||
|
||
### 为什么要轮询查询任务状态？
|
||
|
||
因为绑定/解绑操作是异步的，设备需要时间完成操作。建议间隔3-5秒轮询一次，直到任务状态变为 COMPLETED 或 FAILED。
|
||
|
||
### 信用卡信息为什么要脱敏？
|
||
|
||
为了保护支付安全，任务详情中的信用卡信息只显示脱敏后的卡号和掩码CVV。
|