完成文件上传

最近更新时间:2025-09-30 16:15:11

我的收藏

功能描述

用于完成上传文件。
说明:
要求权限:admin、space_admin、upload_file、upload_file_force 或 confirm_upload。有关权限详情请参见 生成访问令牌接口
在表单上传完成后,请务必及时调用该接口,否则文件将不能被正确存储。
如果调用该接口时实际并未完成文件上传,将返回错误信息。

请求

请求示例

POST /api/v1/file/`{LibraryId}`/`{SpaceId}`/`{ConfirmKey}`?confirm&conflict_resolution_strategy=`{ConflictResolutionStrategy}`&access_token=`{AccessToken}`&user_id=`{UserId}&with_inode={WithInode}`

请求参数

请求参数
描述
类型
是否必选
LibraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
SpaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
ConfirmKey
确认参数,指定为开始上传文件时响应体中的 confirmKey 字段的值
String
ConflictResolutionStrategy
文件名冲突时的处理方式:
ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码。
rename: 冲突时自动重命名文件。
overwrite: 如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件,默认为开始文件上传时指定的 ConflictResolutionStrategy。
String
AccessToken
访问令牌,对于公有读媒体库或租户空间,可不指定该参数,否则必须指定该参数获取请参见 生成访问令牌
String
UserId
用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份,详情请参见 生成访问令牌接口
String
WithInode
0 或 1,是否返回 inode,即文件目录 ID,默认不返回
String

请求体

空或 application/json,可指定 crc64 用于校验上传正确性。
请求体示例:
{
"crc64": "xxx",
"labels":["大象","动物","亚洲象"],
"category":"video",
"localCreationTime": "2022-07-26T02:58:09Z",
"localModificationTime": "2022-07-26T02:58:09Z"
}
请求体字段说明:
请求参数
描述
类型
是否必选
crc64
文件的 CRC64-ECMA182 校验值,如果不指定则不做校验,如果校验失败则返回 HTTP 400 Bad Request 及 BadCrc64 错误码
String
labels
文件标签列表
String Array
category
文件自定义的分类
String
localCreationTime
文件对应的本地创建时间
String
localModificationTime
文件对应的本地修改时间
String

响应

响应码

上传成功,返回 HTTP 200 OK。

响应体

application/json
响应体示例:
{
"path": [ "foo", "bar", "file (1).docx" ],
"name": "file (1).docx",
"type": "file",
"inode": "b63393076d249110000631c316d9751a",
"creationTime": "2020-09-22T07:44:45.000Z",
"modificationTime": "2021-02-01T08:21:47.000Z",
"contentType": "image/jpg",
"size": "1048576",
"eTag": "xxx",
"crc64": "xxx",
"metaData": {
"x-smh-meta-foo": "bar"
},
"virusAuditStatus": 0,
"isOverwritten": false,
"previewByDoc": true,
"previewByCI": true,
"previewAsIcon": false,
"fileType": "word"
}
响应体字段说明:
响应参数
描述
类型
path
字符串数组 或 null,如果是字符串数组则表示最终的文件路径,数组中的最后一个元素代表最终的文件名,其他元素代表每一级目录名,因为可能存在同名文件自动重命名,所以这里的最终路径可能不等同于开始上传时指定的路径;如果是 null 则表示该文件所在的目录或其某个父级目录已被删除,该文件已经无法访问
String
name
最终文件名
String Array
type
文件类型
String
inode
文件目录ID
String
creationTime
文件首次完成上传的时间
String
modificationTime
文件最近一次被覆盖的时间
String
contentType
媒体类型
String
size
文件大小
String
ETag
文件 ETag
String
crc64
文件的 CRC64-ECMA182 校验值
String
metaData
元数据,如果没有元数据则不存在该字段
String
isOverwritten
文件上传时是否发生文件覆盖
Array
previewByDoc
是否可通过 wps 预览
Boolean
previewByCI
是否可通过万象预览
Boolean
previewAsIcon
是否可用预览图作为 icon
Boolean
fileType
文件类型:Excel、PowerPoint 等
String
virusAuditStatus
0-6查毒状态:
0:未检测 (文件夹不标记可疑状态,一直为0)
1:检测中
2:无风险
3:风险文件
4:无法检测 (比如文件太大超过可检测范围,端侧当无风险处理)(超1G不检)
5:人为标记为无风险
6:检测任务失败
String

错误码

该请求操作无特殊错误信息,常见的错误信息请参见 错误码 文档。