Skip to main content

申请 OSS 直传授权

千问办公企业旗舰版开发者文档:申请 OSS 直传授权。

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

接口说明

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

请求参数

字段位置类型必填说明
Idempotency-Keyheaderstring是1–128 个可见 ASCII 字符;同一次上传重试保持相同键和参数
pathbodystring是当前用户的绝对文件路径,如 /Uploads/input.txt;不允许覆盖已有文件
sizebodyinteger是文件总字节数,必须大于 0,受文件大小和容量限制
mime_typebodystring否MIME 类型;未提供时按文件名推断
upload_modebodystring否single(默认)或 multipart;不接受 null
请求为 application/json,不允许未知字段。用户归属、对象 key 及存储位置由服务端确定。

响应

首次申请返回 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 用于每个分片。重放只返回尚未上传的分片。
URL 有有效期且包含敏感签名,应原样使用,不写入日志。OSS 请求设置 credentials: omit,不附带登录凭据。浏览器自动设置 Content-Length。所有分片完成后仍须调用完成接口。

响应字段

字段类型必返约束说明
session_idstring是uuidOSS 直传任务标识,用于完成或取消上传;不是 Agent 会话 ID。
statusstring是—上传任务当前状态;不能以授权申请成功代替上传完成。
uploadobject否—待上传任务的 OSS 授权信息;已完成任务重放时可能省略。
upload_modestring是single、multipart直传方式:single 或 multipart。

upload(single)

字段类型必返约束说明
headersobject<string, string>是—OSS 请求必须携带的请求头,字符串键值对象;不附带 IAM 凭据。
urlstring是—对应对象或分片的预签名上传 URL,含敏感签名,不写入日志。

upload(multipart)

字段类型必返约束说明
headersobject<string, string>是—OSS 请求必须携带的请求头,字符串键值对象;不附带 IAM 凭据。
part_sizeinteger是int64标准分片大小,单位字节。
partsarray<object>是—本次需要上传的分片列表;重放只返回尚未上传的分片。

upload(multipart).parts[]

字段类型必返约束说明
offsetinteger是int64该分片在原文件中的起始字节偏移。
part_numberinteger是int64OSS 分片编号。
sizeinteger是int64本分片实际字节数;末片可能小于标准分片大小。
urlstring是—对应对象或分片的预签名上传 URL,含敏感签名,不写入日志。

调用示例

// 使用 appRequest;重试同一次上传时复用 uploadKey。
const response = await appRequest('/api/openapi/app/v1/drive/direct-uploads', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Idempotency-Key': uploadKey },
  body: JSON.stringify({ path: '/Uploads/input.txt', size: file.size, mime_type: file.type || 'application/octet-stream' }),
});
if (!response.ok) throw new Error(`申请失败:${response.status}`);
const task = await response.json();
if (task.upload) {
  const headers = Object.fromEntries(Object.entries(task.upload.headers).filter(([key]) => key.toLowerCase() !== 'content-length'));
  const put = await fetch(task.upload.url, { method: 'PUT', credentials: 'omit', headers, body: file });
  if (!put.ok) throw new Error(`直传失败:${put.status}`);
}
const complete = await appRequest(`/api/openapi/app/v1/drive/direct-uploads/${encodeURIComponent(task.session_id)}/complete`, {
  method: 'POST',
});
if (!complete.ok) throw new Error(`完成失败:${complete.status}`);
const result = await complete.json();
// 保存 result.file.file_id;Session 附件使用 result.file.path。

使用 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。 OSS PUT 成功通常返回 200,且可能没有响应正文。PUT 失败时先检查返回状态与错误正文,不把失败当作完成。 此命令仅适用于 single 模式。multipart 必须按返回的 offset、size 准备每个分片,使用该分片的 url 和响应 headers,不能把完整文件上传到某个分片 URL。更多说明见阿里云:使用预签名 URL 上传文件。

错误处理

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