千问办公企业旗舰版开发者文档:申请 OSS 直传授权。
认证方式见APP开发者文档 → 认证接入。
当前用户由 IAM 登录态确定,Barn 校验上传任务归属。
请求为 application/json,不允许未知字段。用户归属、对象 key 及存储位置由服务端确定。
首次申请返回 201,幂等重放返回 200;响应包含 session_id、upload_mode、status。pending 时返回 upload,已完成任务重放可能省略 upload。
取得 single 模式的
401 表示认证失败;403 表示 权限或配额拒绝;404 表示任务不属于当前用户或不存在;409 表示任务状态、幂等参数或目标文件冲突;410 表示任务已取消、过期或上传凭证过期;413 表示文件过大;422 表示上传对象与声明不一致;429 表示并发任务过多;503 表示直传未启用、维护或依赖不可用;504 表示请求超时。参数错误可能返回纯文本,先检查状态和 Content-Type。结果未知时不要盲目新建任务。
- 模块:文件服务
- 接口:POST
/api/openapi/app/v1/drive/direct-uploads - operationId:
appCreateDriveDirectUpload
接口说明
当前用户由 IAM 登录态确定,Barn 校验上传任务归属。
请求参数
| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| Idempotency-Key | header | string | 是 | 1–128 个可见 ASCII 字符;同一次上传重试保持相同键和参数 |
| path | body | string | 是 | 当前用户的绝对文件路径,如 /Uploads/input.txt;不允许覆盖已有文件 |
| size | body | integer | 是 | 文件总字节数,必须大于 0,受文件大小和容量限制 |
| mime_type | body | string | 否 | MIME 类型;未提供时按文件名推断 |
| upload_mode | body | string | 否 | single(默认)或 multipart;不接受 null |
响应
首次申请返回 201,幂等重放返回 200;响应包含 session_id、upload_mode、status。pending 时返回 upload,已完成任务重放可能省略 upload。
- single:upload.url 为预签名 PUT 地址;upload.headers 为所需请求头。
- multipart:upload.part_size 为分片大小;upload.parts 包含 part_number、url、offset、size;upload.headers 用于每个分片。重放只返回尚未上传的分片。
响应字段
| 字段 | 类型 | 必返 | 约束 | 说明 |
|---|---|---|---|---|
| session_id | string | 是 | uuid | OSS 直传任务标识,用于完成或取消上传;不是 Agent 会话 ID。 |
| status | string | 是 | — | 上传任务当前状态;不能以授权申请成功代替上传完成。 |
| upload | object | 否 | — | 待上传任务的 OSS 授权信息;已完成任务重放时可能省略。 |
| upload_mode | string | 是 | single、multipart | 直传方式:single 或 multipart。 |
upload(single)
| 字段 | 类型 | 必返 | 约束 | 说明 |
|---|---|---|---|---|
| headers | object<string, string> | 是 | — | OSS 请求必须携带的请求头,字符串键值对象;不附带 IAM 凭据。 |
| url | string | 是 | — | 对应对象或分片的预签名上传 URL,含敏感签名,不写入日志。 |
upload(multipart)
| 字段 | 类型 | 必返 | 约束 | 说明 |
|---|---|---|---|---|
| headers | object<string, string> | 是 | — | OSS 请求必须携带的请求头,字符串键值对象;不附带 IAM 凭据。 |
| part_size | integer | 是 | int64 | 标准分片大小,单位字节。 |
| parts | array<object> | 是 | — | 本次需要上传的分片列表;重放只返回尚未上传的分片。 |
upload(multipart).parts[]
| 字段 | 类型 | 必返 | 约束 | 说明 |
|---|---|---|---|---|
| offset | integer | 是 | int64 | 该分片在原文件中的起始字节偏移。 |
| part_number | integer | 是 | int64 | OSS 分片编号。 |
| size | integer | 是 | int64 | 本分片实际字节数;末片可能小于标准分片大小。 |
| url | string | 是 | — | 对应对象或分片的预签名上传 URL,含敏感签名,不写入日志。 |
调用示例
使用 curl 上传文件
取得 single 模式的 upload.url 后,可在终端执行下面的 PUT 请求。将本地文件路径、完整 URL 和每个请求头的占位值替换为本次响应中的实际值;文件字节数必须与申请时的 size 一致。
-T 发送文件原始字节,不使用 -F 或 FormData。按 upload.headers 原样传入全部请求头;若响应包含其他头,也应逐项增加 -H。
OSS PUT 成功通常返回 200,且可能没有响应正文。PUT 失败时先检查返回状态与错误正文,不把失败当作完成。
此命令仅适用于 single 模式。multipart 必须按返回的 offset、size 准备每个分片,使用该分片的 url 和响应 headers,不能把完整文件上传到某个分片 URL。更多说明见阿里云:使用预签名 URL 上传文件。