init: mipu-open 对外开放项目统一管理仓库
- 添加 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>
This commit is contained in:
128
docs/09-03_device-unbind.md
Normal file
128
docs/09-03_device-unbind.md
Normal file
@@ -0,0 +1,128 @@
|
||||
<!-- mipuyun-api-doc: device-unbind -->
|
||||
# device/unbind - VCC卡解绑
|
||||
|
||||
## 概述
|
||||
|
||||
VCC卡解绑API用于向设备提交VCC卡解绑请求。解绑过程是异步的,提交后会返回任务ID,可以通过任务查询接口查询解绑进度。
|
||||
|
||||
### 用户使用场景
|
||||
|
||||
本接口用于:
|
||||
- 移除设备当前绑定的VCC卡
|
||||
- 更换VCC卡前先解绑旧卡
|
||||
|
||||
## 请求说明
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| **请求地址** | `https://${endpoint}/device/unbind` |
|
||||
| **请求方法** | POST |
|
||||
| **注意事项** | 解绑过程是异步的,需要轮询任务状态 |
|
||||
|
||||
### Header 参数
|
||||
|
||||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||||
|----------|------|----------|--------|------|
|
||||
| Content-Type | String | 是 | application/json | 固定值,指定请求体格式为 JSON |
|
||||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
|
||||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
|
||||
|
||||
### 请求体参数
|
||||
|
||||
```json
|
||||
{
|
||||
"deviceId": "device-001"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||||
|----------|------|----------|--------|------|
|
||||
| deviceId | String | 是 | "device-001" | 设备编号 |
|
||||
|
||||
## 返回参数
|
||||
|
||||
成功时返回任务信息:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "VCC卡解绑任务已提交",
|
||||
"taskId": "task-unbind-123456"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名称 | 类型 | 说明 |
|
||||
|----------|------|------|
|
||||
| success | Boolean | 是否成功提交 |
|
||||
| message | String | 结果消息 |
|
||||
| taskId | String | 任务ID,用于查询任务状态 |
|
||||
|
||||
失败时返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "设备没有绑定的VCC卡",
|
||||
"taskId": null
|
||||
}
|
||||
```
|
||||
|
||||
## 业务案例
|
||||
|
||||
### 解绑VCC卡
|
||||
|
||||
### 请求
|
||||
|
||||
```bash
|
||||
curl -X POST "https://${endpoint}/device/unbind" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "client-key: your_key" \
|
||||
-H "client-secret: your_secret" \
|
||||
-d '{
|
||||
"deviceId": "device-001"
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "VCC卡解绑任务已提交",
|
||||
"taskId": "task-unbind-123456"
|
||||
}
|
||||
```
|
||||
|
||||
### 查询解绑任务进度
|
||||
|
||||
使用返回的taskId查询任务状态:
|
||||
|
||||
```bash
|
||||
curl -X GET "https://${endpoint}/device/task/task-unbind-123456" \
|
||||
-H "client-key: your_key" \
|
||||
-H "client-secret: your_secret"
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 解绑是同步还是异步的?
|
||||
|
||||
解绑是**异步操作**。提交解绑请求后会立即返回任务ID,需要通过任务查询接口轮询任务状态。
|
||||
|
||||
### 解绑失败的可能原因?
|
||||
|
||||
- 设备离线(status=OFFLINE)
|
||||
- 设备正在执行其他任务(taskStatus=PROCESSING)
|
||||
- 设备没有绑定的VCC卡(vccCardNumber为空)
|
||||
|
||||
### 如何判断解绑是否完成?
|
||||
|
||||
通过任务查询接口检查任务状态:
|
||||
- **PENDING**:任务在队列中等待
|
||||
- **PROCESSING**:正在解绑中
|
||||
- **COMPLETED**:解绑完成
|
||||
- **FAILED**:解绑失败
|
||||
|
||||
### 解绑完成后如何验证?
|
||||
|
||||
再次调用设备列表接口,查看设备的 `vccCardNumber` 字段是否已为空。
|
||||
Reference in New Issue
Block a user