分片上传大文件
该接口用于上传大文件,大文件的上传如果不分片会遇到请求 timeout 的情况,也会遭遇因种种原因导致的请求中断而从只能从头再传的问题,所以大文件采用分片上传,一方面解决请求 timeout 的情况,另一方面又提供了断点续传的功能,即用户在发现请求中断后重新上传同一份文件,之前上传的部分就不需要再上传。
POST
接口路径:http://matpool.com:30100/v1/fs/block_file
分片上传原理简述
API 调用方可以根据自己的需要将文件进行分片,当前支持的分片大小有 1M/2M/4M/8M/16M,然后每次请求只上传某一个分片的二进制数据。
- 为了让服务端知道如何拼合分片成完整的文件,调用方还需要传递当前分片的索引
- 为了让服务端知道断点续传前后上传的分片是否属于同一个文件,调用方需要在每次请求中传递整个文件的摘要(MD5)
- 针对每次分片上传请求,服务端不仅会返回上传成功与否,还会返回当前文件还有哪些分片没有上传,便于调用方选择下一个上传的分片
- 断点续传功能可能会在云存储中遗留未完成的文件,占据用户一定的空间,所以建议用户在遇到上传中断的情况下,及时进行续传
Header
Required | Name | Value | Description |
---|---|---|---|
✔︎ | Authorization | Bearer <token> | 用户鉴权 |
Query
Required | Name | Example | Description |
---|---|---|---|
✔︎ | file_name | /data | 上传到云存储中的完整路径,请确保前置目录存在 |
✔︎ | block_size | 2097152 | 块大小,单位为 Byte,当前支持 1M/2M/4M/8M/16M |
✔︎ | file_size | 209715234 | 文件总大小,单位为 Byte |
✔︎ | block_index | 0 | 指示当前上传块的索引,从 0 开始 |
✔︎ | checksum | 8d2...d83 | 当前整个文件的摘要(MD5) |
✔︎ | checksum_alg | 1 | 文件签名算法,当前只支持传入整数 1 ,表示 MD5 |
注意: 如果要传到子目录中,比如 /data/task/file
,在调用前需要保证目录 /data/task
是存在的,否则上传会失败。
Body(formdata)
Required | Name | type | Example | Description |
---|---|---|---|---|
✔︎ | file | file | - | 当前请求对应的文件分片数据 |
Response
Normal
code = 0
示例:调用者根据每次请求的返回可以知道下一次上传哪一个分片,当所有分片都上传完毕,文件即上传成功
{
"code": 0,
"msg": "",
"info": {
"blkWritten": {
"0": true, // 表示索引为 0 的分片已经上传完毕
"1": true,
"2": true,
"3": true,
"4": false, // 表示索引为 4 的分片还没上传
... ...
"34": false,
"35": false,
"36": false // 一共有 37 个分片
}
}
}
Exception
code = 1 || 7 || 17
参见 全局错误码