千问办公企业旗舰版开发者文档:使用指南。
文件服务使用指南
认证方式见APP开发者文档 → 认证接入。
服务与认证
文件服务面向当前认证用户的文件,适用于网盘、聊天附件及其他文件业务。文件管理与容量查询使用 /api/openapi/app/v1/drive,由 Barn 校验资源归属。
本目录收录 15 个文件管理、容量查询与直传操作(含 HEAD)。文件归属由服务端确定。
接口目录
以下路径均相对于 /api/openapi/app/v1/drive。HEAD 不返回正文。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET / HEAD | /files | 使用 query path 或 file_id 读取文件;GET 返回文件信息与可选下载地址 |
| PATCH | /files | 使用 query path 或 file_id 重命名;路径模式还支持修改 metadata |
| DELETE | /files | 使用 query path 或 file_id 删除文件或目录;递归删除须显式 recursive=true |
| GET / HEAD | /directories/{path} | 按路径浏览目录,支持 limit/offset、sort/order |
| GET | /directories | 使用 query file_id 浏览目录,支持 limit/offset,按路径升序 |
| POST | /directories/{path} | 创建目录,可附带 metadata |
| POST | /copy/{path} | 将 from_path 或 from_file_id 指定的源复制到目标路径 |
| GET / HEAD | /search | 使用 q、q_type=filename 搜索,可附带 file_type、limit、offset |
| GET | /quota | 查询本人容量上限、已用容量及文件大小限制,单位为字节 |
| POST | /direct-uploads | 申请 OSS 直传授权,要求 Idempotency-Key |
| POST | /direct-uploads/{session_id}/complete | 校验对象并登记文件,支持重复确认 |
| DELETE | /direct-uploads/{session_id} | 取消未完成上传并释放配额预占 |
{path} 表示完整逻辑路径。详细参数、响应和错误处理见对应接口页。
左侧“文件服务 → 文件与目录”包含上述 11 个文件操作,“存储配额”包含 1 个容量查询,“OSS 直传”包含 3 个上传操作。GET 与 HEAD 各计一个操作;按路径和按 ID 读取文件共用同一个 /files 接口,按 ID 列目录则使用独立的 /directories 接口。
文件 ID 与业务引用
文件详情、目录及子项、搜索、创建和复制的文件信息均包含 file_id。它是当前用户文件空间内的稳定 UUID:文件或父目录重命名后保留,复制会生成新 ID,删除后同路径重建不会复用旧 ID。
- 从文件详情、目录列表或搜索结果取得 file_id。
- 使用
GET /files?file_id={uuid}读取文件及下载地址。 - 使用
PATCH /files?file_id={uuid},提交{"filename":"new.txt"}重命名;ID 模式只接收 filename,原元数据保留。 - 使用
POST /copy/目标路径,提交{"from_file_id":"源 UUID"}复制,并保存目标响应的新 file_id。源也可以使用 from_path,两者不能同时提交。 - 使用
GET /directories?file_id={uuid}浏览目录,或DELETE /files?file_id={uuid}删除。
path。file_id 用于稳定定位文件,不能替换到附件路径字段中。
读取、下载与响应
文件响应使用 presigned_url,目录结果使用 children、total,搜索结果使用 results、total。这些字段不使用旧接口的 download_url 或 items 命名。
按路径读取时可指定 mode=download;mode 默认 download,预览可指定 preview,编辑可指定 edit。按 ID 读取返回下载地址,不应用 mode/size 预览选项。目录或其他未生成访问地址的响应可能省略 presigned_url。
下载地址有有效期,应原样使用;失效后重新获取。向 OSS 地址请求时不要附带 业务认证凭据。
OSS 直传流程
上传分三步:调用业务接口申请上传授权,向返回的 OSS 地址发送文件,再调用完成接口校验与登记。这里的授权是预签名 URL 和请求头,不返回可用于其他对象的通用 STS Token。上传任务 session_id 与登记后的 file_id 是不同对象。
POST /direct-uploads:提交 path、size(字节)、可选 mime_type 和 upload_mode,写请求按契约携带Idempotency-Key。upload_mode 默认 single,也支持 multipart。- single 模式将完整文件 PUT 到 upload.url,并使用 upload.headers;multipart 模式按 upload.parts 中的 offset、size 切片,分别 PUT 到每项 url,使用 upload.headers。所有文件字节直接发送至 OSS。
POST /direct-uploads/{session_id}/complete:服务端检查对象、大小、上传归属并登记文件,返回 session_id、status 和 file。保存 file.file_id 作为稳定引用;Session 附件仍使用 file.path。
DELETE /direct-uploads/{session_id} 取消未完成任务并释放配额预占,成功返回 204;不能取消已完成文件。跨用户完成或取消返回 404。
直传未启用时返回 503 DIRECT_UPLOAD_DISABLED。地址和任务均有有效期;过期、配额不足、文件大小不匹配或名称冲突须按实际错误处理。只有完成登记后,文件才可通过文件接口读取;完成不代表异步审核已经通过。
Barn 接收分片、普通代理上传和个人 WebOffice 不属于公开接口。OSS multipart 的分片直接发送到 OSS,属于本页的直传流程。
使用 curl 上传文件
取得 single 模式的 upload.url 后,可在终端执行下面的 PUT 请求。将本地文件路径、完整 URL 和每个请求头的占位值替换为本次响应中的实际值;文件字节数必须与申请时的 size 一致。
-T 发送文件原始字节,不使用 -F 或 FormData。按 upload.headers 原样传入全部请求头;若响应包含其他头,也应逐项增加 -H。URL 必须保留完整查询参数并加引号,不附带 业务认证凭据。
OSS PUT 成功通常返回 200,且可能没有响应正文。随后仍须调用 POST /api/openapi/app/v1/drive/direct-uploads/{session_id}/complete;完成登记后才能使用文件。PUT 失败时先检查返回状态与错误正文,不把失败当作完成。
此命令仅适用于 single 模式。multipart 必须按返回的 offset、size 准备每个分片,使用该分片的 url 和响应 headers,不能把完整文件上传到某个分片 URL。更多说明见阿里云:使用预签名 URL 上传文件。
容量与错误处理
GET /quota 返回 max_storage_bytes、used_storage_bytes、max_file_size_bytes,均为字节。零值保持零,查询失败应显示容量不可用;页面展示不替代上传时服务端的配额校验。接口不接受 user_id 等查询参数。
先检查 HTTP 状态和 Content-Type,再解析正文。业务错误通常为 {"code":"错误码","message":"说明"},鉴权失败可能没有正文,部分参数错误可能为纯文本。
400/422 检查参数;401 检查认证状态;403 检查资源权限;404 检查当前用户与资源;409 检查名称或状态冲突。503/504 不表示写操作已经成功,结果未知时先查询资源状态,不盲目重试。