104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
|
||
# drive +delete
|
||
|
||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||
|
||
删除云空间（云盘/云存储）内的文件或文件夹。删除后资源会进入回收站。
|
||
|
||
> [!CAUTION]
|
||
> 这是**高风险写操作**。CLI 层要求显式传 `--yes`；如果用户已经明确要求删除且目标明确，直接执行并带上 `--yes`。
|
||
> “目标明确”表示用户给出了可解析为 `file-token` + `type` 的具体 URL/token，或对你刚列出的可解析资源列表逐项/整批确认删除。按“没用的”“临时的”“疑似重复的”“全部旧文件”等描述搜索出来的候选属于待确认目标；这类请求先列候选、说明筛选依据和影响范围，然后停止等待确认。
|
||
|
||
## 删除前门槛
|
||
|
||
执行 `drive +delete --yes` 前同时满足：
|
||
|
||
| 条件 | 可执行信号 |
|
||
|------|------------|
|
||
| 具体目标 | 单个可解析为 `file-token` + `type` 的 URL/token，或用户确认过且可解析的资源列表 |
|
||
| 执行确认 | 用户在本轮明确说确认删除这些具体目标 |
|
||
|
||
若缺少任一条件，使用 `drive +search`、`drive +inspect` 或只读 API 收集候选并回复待确认清单；启发式规则（打开时间、标题模式、owner、文件类型等）只能作为候选筛选依据，不能升级为删除确认。执行 `drive +delete` 时必须使用解析后的 `--file-token` 和 `--type`。
|
||
|
||
## 批量删除建议
|
||
|
||
批量删除文件或文件夹时，建议逐个串行处理，不要并发执行删除命令，并发删除可能触发服务端加锁或冲突，导致部分删除失败；这类失败通常需要等待后对单个失败项重试。
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
# 删除普通文件（异步操作，会自动有限轮询任务状态）
|
||
lark-cli drive +delete \
|
||
--file-token <FILE_TOKEN> \
|
||
--type file \
|
||
--yes
|
||
|
||
# 删除在线文档（异步操作，会自动有限轮询任务状态）
|
||
lark-cli drive +delete \
|
||
--file-token <DOCX_TOKEN> \
|
||
--type docx \
|
||
--yes
|
||
|
||
# 删除文件夹（异步操作，会自动有限轮询任务状态）
|
||
lark-cli drive +delete \
|
||
--file-token <FOLDER_TOKEN> \
|
||
--type folder \
|
||
--yes
|
||
```
|
||
|
||
## 参数
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--file-token` | 是 | 需要删除的文件或文件夹 token |
|
||
| `--type` | 是 | 文件类型，可选值：`file`、`docx`、`bitable`、`doc`、`sheet`、`mindnote`、`folder`、`shortcut`、`slides` |
|
||
| `--yes` | 是 | 确认执行高风险删除操作 |
|
||
|
||
## 行为说明
|
||
|
||
- **删除可能需要等待**：删除操作在服务端可能异步处理，shortcut 会在本次命令内自动做有限次数的结果轮询
|
||
- **已完成则停止**：如果返回 `deleted=true`，且没有返回 `next_command`，说明删除已经完成，不需要再调用 `drive +task_result`
|
||
- **未完成再续查**：如果超过内置轮询次数仍未完成，会返回 `ready=false`、`timed_out=true`、`task_id` 和 `next_command`；此时按 `next_command` 继续查询删除结果
|
||
- **task_id 不是成功条件**：`task_id` 只是续查凭据。没有 `task_id` 但返回 `deleted=true` 时，也表示删除已完成
|
||
- **失败处理**：如果返回 `failed=true` 或 `status=fail`，按错误信息和 `task_id` 报告删除失败；不要重复删除同一资源
|
||
|
||
## 常见错误处理
|
||
|
||
| 错误码 | 含义 | 建议处理 |
|
||
|--------|------|----------|
|
||
| `1061007` | 文件已删除 | 视为目标已不可用，无需重试删除 |
|
||
| `99991400` | 命中接口限频 | 等待一段时间后重试；批量删除时保持串行并降低频率 |
|
||
| `99991679` | 缺失 scope | 按错误里的 `missing_scopes`、`hint` 申请/授权所需 scope 后重试 |
|
||
|
||
## 推荐续跑方式
|
||
|
||
```bash
|
||
# 第一步：先直接删除资源
|
||
lark-cli drive +delete \
|
||
--file-token <FILE_OR_FOLDER_TOKEN> \
|
||
--type <TYPE> \
|
||
--yes
|
||
|
||
# 只有返回 ready=false / timed_out=true 或 next_command 时，才需要继续查
|
||
lark-cli drive +task_result \
|
||
--scenario task_check \
|
||
--task-id <TASK_ID>
|
||
```
|
||
|
||
## 限制
|
||
|
||
- 该 shortcut 仅支持云空间（云盘/云存储）文件或文件夹，不支持 wiki 文档
|
||
- 该接口不支持并发调用
|
||
- 调用频率上限为 5 QPS 且 10000 次/天
|
||
|
||
## 权限要求
|
||
|
||
- 删除文件时，调用身份需要满足以下其一：
|
||
- 是文件所有者，并且拥有该文件所在父文件夹的编辑权限
|
||
- 不是文件所有者，但拥有该父文件夹的 owner 或 full access 权限
|
||
|
||
## 参考
|
||
|
||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|