Skip to main content

使用指南

千问办公企业旗舰版开发者文档:使用指南。

文件服务使用指南

认证方式见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}取消未完成上传并释放配额预占
文件操作中的 query path 必须用 URLSearchParams 编码;目录与复制的 {path} 表示完整逻辑路径。详细参数、响应和错误处理见对应接口页。 左侧“文件服务 → 文件与目录”包含上述 11 个文件操作,“存储配额”包含 1 个容量查询,“OSS 直传”包含 3 个上传操作。GET 与 HEAD 各计一个操作;按路径和按 ID 读取文件共用同一个 /files 接口,按 ID 列目录则使用独立的 /directories 接口。

文件 ID 与业务引用

文件详情、目录及子项、搜索、创建和复制的文件信息均包含 file_id。它是当前用户文件空间内的稳定 UUID:文件或父目录重命名后保留,复制会生成新 ID,删除后同路径重建不会复用旧 ID。
  1. 从文件详情、目录列表或搜索结果取得 file_id。
  2. 使用 GET /files?file_id={uuid} 读取文件及下载地址。
  3. 使用 PATCH /files?file_id={uuid},提交 {"filename":"new.txt"} 重命名;ID 模式只接收 filename,原元数据保留。
  4. 使用 POST /copy/目标路径,提交 {"from_file_id":"源 UUID"} 复制,并保存目标响应的新 file_id。源也可以使用 from_path,两者不能同时提交。
  5. 使用 GET /directories?file_id={uuid} 浏览目录,或 DELETE /files?file_id={uuid} 删除。
path 与 file_id 必须二选一,ID 必须是单个非零 UUID。其他用户的 ID 返回 404。按 ID 复制目录沿用 100 项(含根)的上限及部分失败语义,失败或结果未知时先查询目标,再决定是否重试。 Session 附件继续按其接口契约传递 path。file_id 用于稳定定位文件,不能替换到附件路径字段中。

读取、下载与响应

文件响应使用 presigned_url,目录结果使用 children、total,搜索结果使用 results、total。这些字段不使用旧接口的 download_url 或 items 命名。 按路径读取时可指定 mode=download;mode 默认 download,预览可指定 preview,编辑可指定 edit。按 ID 读取返回下载地址,不应用 mode/size 预览选项。目录或其他未生成访问地址的响应可能省略 presigned_url。 下载地址有有效期,应原样使用;失效后重新获取。向 OSS 地址请求时不要附带 业务认证凭据。
const query = new URLSearchParams({ file_id: savedFileId });
const response = await appRequest(`/api/openapi/app/v1/drive/files?${query}`, {

});
if (!response.ok) throw new Error(`读取失败:${response.status}`);
const file = await response.json();
// file.file_id 是稳定 ID;file.path 是当前路径。
// file.presigned_url 有值时,用独立请求访问,不附带登录凭据。

OSS 直传流程

上传分三步:调用业务接口申请上传授权,向返回的 OSS 地址发送文件,再调用完成接口校验与登记。这里的授权是预签名 URL 和请求头,不返回可用于其他对象的通用 STS Token。上传任务 session_id 与登记后的 file_id 是不同对象。
  1. POST /direct-uploads:提交 path、size(字节)、可选 mime_type 和 upload_mode,写请求按契约携带 Idempotency-Key。upload_mode 默认 single,也支持 multipart。
  2. single 模式将完整文件 PUT 到 upload.url,并使用 upload.headers;multipart 模式按 upload.parts 中的 offset、size 切片,分别 PUT 到每项 url,使用 upload.headers。所有文件字节直接发送至 OSS。
  3. POST /direct-uploads/{session_id}/complete:服务端检查对象、大小、上传归属并登记文件,返回 session_id、status 和 file。保存 file.file_id 作为稳定引用;Session 附件仍使用 file.path。
业务请求使用 appRequest;对象存储请求使用返回的 URL 和 headers,不附带业务认证凭据。浏览器自动设置 Content-Length。 首次申请返回 201,相同用户以相同 Idempotency-Key 和参数重试返回 200;同一键换参数返回 409。申请响应未知时使用原键和原参数重试。multipart 重试返回尚未完成分片的签名地址。已完成任务重放可能省略 upload,此时重复调用完成接口取得文件信息。 正常上传不依赖未完成任务列表。本目录不提供上传任务列表或独立状态查询;PUT 或完成响应未知时,重试完成确认,尚未收到完整对象返回 409。不要据此重新创建任务或覆盖对象。单链接 PUT 不支持断点续传;multipart 可通过相同申请重放恢复缺失分片。 DELETE /direct-uploads/{session_id} 取消未完成任务并释放配额预占,成功返回 204;不能取消已完成文件。跨用户完成或取消返回 404。 直传未启用时返回 503 DIRECT_UPLOAD_DISABLED。地址和任务均有有效期;过期、配额不足、文件大小不匹配或名称冲突须按实际错误处理。只有完成登记后,文件才可通过文件接口读取;完成不代表异步审核已经通过。 Barn 接收分片、普通代理上传和个人 WebOffice 不属于公开接口。OSS multipart 的分片直接发送到 OSS,属于本页的直传流程。

使用 curl 上传文件

取得 single 模式的 upload.url 后,可在终端执行下面的 PUT 请求。将本地文件路径、完整 URL 和每个请求头的占位值替换为本次响应中的实际值;文件字节数必须与申请时的 size 一致。
UPLOAD_URL='复制本次响应中的完整 upload.url'
curl --fail-with-body -X PUT -T '/path/to/local/file' \
  -H 'Content-Type: <upload.headers 中的 Content-Type>' \
  -H 'Content-Length: <upload.headers 中的 Content-Length>' \
  -H 'x-oss-forbid-overwrite: <upload.headers 中的 x-oss-forbid-overwrite>' \
  -H 'x-oss-object-acl: <upload.headers 中的 x-oss-object-acl>' \
  -H 'x-oss-meta-direct-session: <upload.headers 中的 x-oss-meta-direct-session>' \
  "$UPLOAD_URL"
-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 不表示写操作已经成功,结果未知时先查询资源状态,不盲目重试。