有奖捉虫:办公协同&微信生态&物联网文档专题 HOT

功能描述

用于开始表单上传文件。

接口说明

要求权限:
非 acl 鉴权:admin、space_admin 或 upload_file/upload_file_force/begin_upload/begin_upload_force
acl 鉴权:canUpload(当前文件夹可上传)
说明
非 acl 鉴权是指当前用户对所有文件的操作权限,详情可参考 生成访问令牌接口
acl 鉴权是通过共享授权接口给指定用户,以文件夹为单位授予的权限,详情可参考 角色授权模块
调用该接口将返回一系列用于 form 表单上传(multipart/form-data 格式)和确认上传完成的参数,上传的目标 URL 为 https://{Domain}/,其中 Domain 为响应体中的 domain 字段,例如 https://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/
form 表单上传时还需要指定一系列额外的信息字段,这些字段的名和值包含在响应体中的 form 字段中,可以在 HTML form 表单中通过隐藏域或通过 JS 相关库、小程序 wx.uploadFile 等指定这些字段。
form 表单中的文件字段,其表单字段名固定为 file,且必须作为表单中的最后一项。
在完成实际上传后,上传的目标 URL 将返回 HTTP 204 No Content,由于可能的跨域限制,建议直接通过相关接口的回调来判断是否上传完成,并且在上传完成后及时调用完成上传文件接口,确认上传结果。
默认情况下同名文件将自动修改文件名,可在完成上传文件接口中获取最终的文件路径。
不会自动创建所需的各级父目录,所以必须保证路径的各级目录存在。

请求

请求示例

POST /api/v1/file/{LibraryId}/{SpaceId}/{FilePath}?conflict_resolution_strategy={ConflictResolutionStrategy}&filesize={FileSize}&access_token={AccessToken}&user_id={UserId}
请求参数:
LibraryId:媒体库 ID,必选参数。
SpaceId:空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数。
FilePath:完整文件路径,例如 foo/bar/file.docx
FileSize:上传文件大小,单位为字节(Byte),用于判断剩余空间是否足够,可选参数。
ConflictResolutionStrategy:文件名冲突时的处理方式。
ask:冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码。
rename:冲突时自动重命名文件
overwrite:如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件,默认为 rename。
AccessToken:访问令牌,必选参数。
UserId:用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份,详情请参阅 生成访问令牌接口,可选参数。

请求头部

x-smh-meta-*:自定义元数据。

请求体

该请求无请求体。

响应

响应码

上传任务创建成功,返回 HTTP 201 Created。

响应体

application/json
响应体示例:
{
"domain": "examplebucket-1250000000.cos.ap-beijing.myqcloud.com",
"form": {
"key": "xxx",
"acl": "default",
"Content-Type": "image/jpeg",
"x-cos-security-token": "xxx",
"policy": "xxx",
"q-sign-algorithm": "sha1",
"q-ak": "xxx",
"q-key-time": "xxx",
"q-signature": "xxx"
},
"confirmKey": "xxx",
"expiration": "2021-07-24T10:34:32.000Z"
}
响应体字段说明:
domain:字符串,实际上传文件时的域名。
form:键值对,实际上传时除文件字段以外需要指定的其他字段,这些字段应当在文件字段之前。
confirmKey:字符串,用于完成文件上传的确认参数。
expiration:上传信息有效期,超过有效期后将失效,需要重新调用本接口获取新的上传参数。