文件上传API

接口说明

注意：本文档提供的文件上传接口是通过直连的方式进行上传。即调用者通过调用api获取上传url，然后由调用者自己通过上传url将文件流进行上传，上传完成后，通过调用相应的提交完成接口，以完成整个文件上传流程。

单个文件上传流程：获取单个文件上传签名 -> 上传文件流 -> 提交单个文件上传

分片文件上传流程：发起文件分片上传任务-> 获取分片上传签名 -> 上传分片文件流 -> 完成分片上传

我们建议大文件走分片文件上传流程，方便网络波动等原因造成文件上传失败后，可以进行断点续传，而不需要重新进行文件上传。进行分片上传时，每一片大小必须至少为5MB，最后一片大小不做限制。每次分片上传后返回的eTag信息，调用者需自行进行保存记录，以便最后完成分片上传时需要。

注意： 获取单个文件上传签名和获取分片上传签名，都会返回上传签名url，以及对应的请求类型method和请求头header信息，如果header为null，则不需要设置请求头信息

获取单个文件上传签名

POST /v1/stream/upload

请求类型（Content-Type）

• application/json

请求参数

参数名	数据类型	必填	参数位置	参数说明
fileHash	String	N	body	文件Hash值
fileName	String	N	body	文件名称

返回结果

状态码	说明	返回值	响应头
200	succeed	UploadSignResult	无
400	failure	String	无

请求示例

POST /v1/stream/upload
Content-Type: application/json

{
"fileHash": "fileHash",
"fileName": "fileName"
}

返回示例

成功：

Content-Type: */*

{
    "code": 200,
    "message": null,
    "data": {
        "url": "signUrl",
        "method": "PUT",
        "headers": null,
        "uploadId": "uploadId"
    },
    "date": 1635842291080
}

失败：

{
    "code": 400,
    "message": "Failed to get upload sign",
    "data": null,
    "date": 1635823240129
}

提交单个文件上传

POST /v1/stream/upload/commit

请求类型（Content-Type）

• application/json

请求参数

参数名	数据类型	必填	参数位置	参数说明
uploadId	String	Y	body	上传id
ondup	Boolean	N	body	如果有同名文件，是否覆盖(默认为false)
dirId	String	Y	body	文件夹id
fileName	String	Y	body	文件名称
fileSize	Long	Y	body	文件大小
fileHash	String	N	body	文件hash
partETags	String	N	body	分片上传eTag信息（(单文件上传时，不必传ETag信息)）

返回结果

状态码	说明	返回值	响应头
200	succeed	FileInfoResult	无
400	failure	String	无
430011	操作权限不足	String	无
430001	父文件夹不存在	String	无
430015	主体配额不足	String	无
430016	企业配额不足	String	无
430012	文件不安全	String	无
430005	文件名超过系统长度	String	无

请求示例

POST /v1/stream/upload/commit
Content-Type: application/json

{
"uploadId": "uploadId", 
"ondup": false,
"dirId": "dirId",
"fileName": "fileName"
"fileSize": 0
"fileHash": "fileHash"
}

返回示例

成功：

Content-Type: */*

{
    "code": 200,
    "message": null,
    "data": {
        "id": "id",
        "name": "fileName",
        "fileExt": "fileExt",
        "size": 0,
        "version": 1,
        "fileHash": "fileHash",
        "locked": false,
        "lockedAt": null,
        "createdAt": 1635845741488,
        "updatedAt": 1635845741488,
        "permissions": {
            "uploadable": true,
            "previewable": true,
            "deleteable": true,
            "shareable": true,
            "downloadable": true,
            "editable": true,
            "restoreable": true,
            "manageable": true,
            "lockable": false,
            "unlockable": false,
            "readable": true
        }
    },
    "date": 1635846813999
}

失败：

{
    "code": 400,
    "message": "Failed to upload the submitted file",
    "data": null,
    "date": 1635823240129
}

发起文件分片上传任务

POST /v1/stream/multipart/upload/start

请求参数

无

返回结果

状态码	说明	返回值	响应头
200	succeed	String	无
400	failure	String	无

请求示例

GET /v1/stream/multipart/upload/start

返回示例

成功：

Content-Type: */*

{
    "code": 200,
    "message": null,
    "data": "uploadId",
    "date": 1635904289433
}

失败：

{
    "code": 400,
    "message": "Failed to get multiPart upload id",
    "data": null,
    "date": 1635823240129
}

获取分片上传签名

POST /v1/stream/multipart/upload/parts

请求参数

参数名	数据类型	必填	参数位置	参数说明
uploadId	String	Y	body	上传id
partNumber	Integer	Y	body	分片编号(1 到 10,000中任何数字)

返回结果

状态码	说明	返回值	响应头
200	succeed	UploadSignResult	无
400	failure	String	无

请求示例

POST /v1/stream/multipart/upload/parts
Content-Type: application/json

{
"uploadId": "uploadId",
"partNumber": "partNumber"
}

返回示例

成功：

Content-Type: */*

{
    "code": 200,
    "message": null,
    "data": {
        "url": "partUrl",
        "method": "PUT",
        "headers": null,
        "uploadId": "uploadId"
    },
    "date": 1635904951870
}

失败：

{
    "code": 400,
    "message": "Failed to get [partNumber] part sign",
    "data": null,
    "date": 1635823240129
}

完成分片上传

POST /v1/stream/multipart/upload/commit

请求参数

参数名	数据类型	必填	参数位置	参数说明
uploadId	String	Y	body	上传id
ondup	Boolean	N	body	如果有同名文件，是否覆盖(默认为false)
dirId	String	Y	body	文件夹id
fileName	String	Y	body	文件名称
fileSize	Long	Y	body	文件大小
fileHash	String	N	body	文件hash
partETags	String	N	body	分片上传eTag信息（(单文件上传时，不必传ETag信息)）

partETags json格式如："[{'eTag': 'eTag', 'partNumber': '1'}]" 或者 "[{'etag': 'eTag', 'partnumber': '1'}]"

返回结果

状态码	说明	返回值	响应头
200	succeed	FileInfoResult	无
400	failure	String	无
430011	操作权限不足	String	无
430001	父文件夹不存在	String	无
430015	主体配额不足	String	无
430016	企业配额不足	String	无
430012	文件不安全	String	无
430005	文件名超过系统长度	String	无

请求示例

POST /v1/stream/multipart/upload/commit
Content-Type: application/json

{
"uploadId": "uploadId", 
"ondup": false,
"dirId": "dirId",
"fileName": "fileName"
"fileSize": 0
"fileHash": "fileHash"
"partETags": "[{'eTag': 'eTag1', 'partNumber': '1'}, {'eTag': 'eTag2', 'partNumber': '2'}]"
}

返回示例

成功：

Content-Type: */*

{
    "code": 200,
    "message": null,
    "data": {
        "id": "id",
        "name": "fileName",
        "fileExt": "fileExt",
        "size": 0,
        "version": 1,
        "fileHash": "fileHash",
        "locked": false,
        "lockedAt": null,
        "createdAt": 1635845741488,
        "updatedAt": 1635845741488,
        "permissions": {
            "uploadable": true,
            "previewable": true,
            "deleteable": true,
            "shareable": true,
            "downloadable": true,
            "editable": true,
            "restoreable": true,
            "manageable": true,
            "lockable": false,
            "unlockable": false,
            "readable": true
        }
    },
    "date": 1635846813999
}

失败：

{
    "code": 400,
    "message": "Fragment uploading failed",
    "data": null,
    "date": 1635823240129
}

获取文件下载签名

POST /v1/stream/download

请求参数

参数名	数据类型	必填	参数位置	参数说明
fileId	String	Y	body	文件id
version	Integer	N	body	文件版本号

返回结果

状态码	说明	返回值	响应头
200	succeed	String	无
400	failure	String	无
430003	找不到资源	String	无
430012	文件不安全	String	无

请求示例

POST /v1/stream/download
Content-Type: application/json

{
"fileId": "fileId",
"version": "version"
}

返回示例

成功：

Content-Type: */*

{
    "code": 200,
    "message": null,
    "data": "downloadSignUrl",
    "date": 1638153949260
}

失败：

{
    "code": 430003,
    "message": "找不到资源，请刷新后重试",
    "data": null,
    "date": 1638153587477
}

删除文件

POST /v1/files/delete

请求参数

参数名	数据类型	必填	参数位置	参数说明
fileIds	json数组	Y	body	文件id集合（可以一个也可以多个）

返回结果

状态码	说明	返回值	响应头
200	succeed	String	无
400	failure	String	无
430003	找不到资源	String	无
430011	操作权限不足	String	无

请求示例

POST /v1/files/delete
Content-Type: application/json

['fileId']

返回示例

成功：

Content-Type: */*

{
    "code": 200,
    "message": null,
    "data": "Deleted successfully",
    "date": 1638153949260
}

失败：

{
    "code": 430003,
    "message": "找不到资源，请刷新后重试",
    "data": null,
    "date": 1638153587477
}