Skip to main content

完成 OSS 直传

千问办公企业旗舰版开发者文档:完成 OSS 直传。

认证方式见APP开发者文档 → 认证接入。
  • 模块:文件服务
  • 接口:POST/api/openapi/app/v1/drive/direct-uploads/{session_id}/complete
  • operationId:appCompleteDriveDirectUpload

接口说明

当前用户由 IAM 登录态确定,Barn 校验上传任务归属。

请求参数

字段位置类型必填说明
session_idpathstring (UUID)是申请直传得到的任务 ID,不是 file_id
无需请求体。single 必须已完成整个文件 PUT;multipart 必须已上传所有分片,服务端负责合并与校验。

响应

200 返回 session_id、status(completed)和 file。file 与读取文件接口使用同一结构,包含稳定 file_id、path、size、mime_type、is_directory、source、metadata、created_at、modified_at,以及可选 presigned_url、moderation_state 等字段。 服务端验证对象归属、大小与任务状态,再登记元数据并结算预占容量。重复完成返回同一文件 ID。完整对象尚未到达时返回 409,大小或类型校验失败返回 422。完成结果未知时重试本接口;完成不表示异步审核已经通过。

响应字段

字段类型必返约束说明
fileobject是—完成登记后的文件信息,字段见下表。
session_idstring是—OSS 直传任务标识,用于完成或取消上传;不是 Agent 会话 ID。
statusstring是—上传任务当前状态;不能以授权申请成功代替上传完成。

响应字段.file

字段类型必返约束说明
created_atstring是date-time创建时间,RFC 3339。
display_namestring否—服务端提供的展示名称,可能省略。
file_idstring是uuid当前用户网盘中的稳定文件/目录 UUID;重命名不改变,复制生成新 ID。
is_directoryboolean是—是否为目录。
metadataobject<string, string>是—字符串键值元数据;无元数据时为 {}。
mime_typestring是—MIME 类型;目录为 application/x-directory。
moderation_statestring否—文件审核状态;未提供时不应推断审核已通过。
modified_atstring是date-time最后修改时间,RFC 3339。
pathstring是—当前用户可见的绝对逻辑路径。
presigned_urlstring否—临时访问 URL,可能省略;原样使用,不附带登录凭据。
sizeinteger是int64大小,单位字节;目录按服务端累计大小返回。
sourcestring是—服务端记录的文件来源,不由客户端据此判断权限。
storage_pathstring否—带隔离前缀的逻辑存储路径,不是 OSS 对象 key;仅部分响应提供。

错误处理

401 表示认证失败;403 表示 权限或配额拒绝;404 表示任务不属于当前用户或不存在;409 表示任务状态、幂等参数或目标文件冲突;410 表示任务已取消、过期或上传凭证过期;413 表示文件过大;422 表示上传对象与声明不一致;429 表示并发任务过多;503 表示直传未启用、维护或依赖不可用;504 表示请求超时。参数错误可能返回纯文本,先检查状态和 Content-Type。结果未知时不要盲目新建任务。