Drive 目前为 Beta 功能，接口定义、响应结构和行为可能发生变化。请关注文档更新，并在生产环境使用前完成兼容性验证。
DELETE /api/v1/forward/drives/entries
请求头
| Header | 是否必填 | 说明 |
|---|
| Authorization | 是 | Bearer <PAT 或 SAT> |
| Content-Type | 是 | application/json |
查询参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|
| identity_id | string | 是 | 当前认证范围内的 Identity ID，只能出现一次；Identity 级 SAT 只能选择其绑定的 Identity。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|
| path | string | 是 | 目标文件或目录的相对路径，不能为根目录。 |
| recursive | boolean | 否 | 默认 false。删除非空目录必须为 true；为 true 时同时删除同路径文件（如有）及目录下全部对象。 |
路径规则
- 使用有效 UTF-8 相对路径，如
projects/reports，不接受绝对路径，如 /projects/reports 或 C:/projects/reports。
- 使用
/ 分隔目录，不允许开头或结尾的 /、连续 /、反斜杠，以及 .、.. 路径段。
- 不允许首尾空白、控制字符或
%（包括 projects%2Freports 这样的转义文本）。
示例请求
curl --silent --show-error --fail-with-body -X DELETE \
"https://api.qoder.com/api/v1/forward/drives/entries?identity_id=idn_xxx" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"path": "projects/demo",
"recursive": true
}'
示例响应
HTTP 200 OK
响应字段
| 字段 | 类型 | 说明 |
|---|
| deleted_count | integer | 本次确认删除的存储对象数；目标不存在时为 0。 |
| HTTP | Code | 触发条件 |
|---|
| 400 | invalid_drive_path | 路径无效或试图删除根目录，或 Identity 标识格式不合法。 |
| 400 | — | 请求体不是合法 JSON、字段类型错误或包含未知字段。 |
| 400 | invalid_identity_id | identity_id 缺失、为空或重复传入。 |
| 401 | — | 凭证缺失或无效；Service Account Key 需先换取 SAT。 |
| 403 | identity_mismatch | Identity 级 SAT 选择了其他 Identity。 |
| 404 | identity_not_found | 当前认证范围内未找到 Identity。 |
| 409 | drive_directory_not_empty | 目录非空且 recursive 不为 true。 |
| 413 | — | 请求体超过服务限制。 |
| 500 | — | 服务内部错误。 |
| 503 | drive_delete_partial | 删除未全部完成；error.deleted_count 给出本次已确认删除数量，可重试原请求。 |
| 503 | drive_unavailable | Drive 存储、签名或依赖能力暂不可用。 |
HTTP 错误响应
{
"type": "error",
"request_id": "req_xxx",
"error": {
"type": "invalid_request_error",
"code": "invalid_drive_path",
"message": "Invalid Drive path."
}
}
响应字段
| 字段 | 类型 | 说明 |
|---|
| type | string | 固定为 error。 |
| request_id | string | 请求追踪 ID，可用时返回。 |
| error.type | string | 错误大类，如 invalid_request_error、authentication_error、permission_error、not_found_error、conflict_error、api_error。 |
| error.code | string | 业务错误码，部分公共错误不返回此字段。 |
| error.message | string | 错误描述。 |
| error.deleted_count | integer | 仅 drive_delete_partial 返回，表示本次已确认删除的对象数，也可能为 0。 |
drive_delete_partial 表示删除未全部完成；已删除的文件不会恢复，重试只处理剩余文件。
入口鉴权错误可能使用不同的响应结构。
