分片上传大文件

该接口用于上传大文件,大文件的上传如果不分片会遇到请求 timeout 的情况,也会遭遇因种种原因导致的请求中断而从只能从头再传的问题,所以大文件采用分片上传,一方面解决请求 timeout 的情况,另一方面又提供了断点续传的功能,即用户在发现请求中断后重新上传同一份文件,之前上传的部分就不需要再上传。

POST

接口路径:http://matpool.com:30100/v1/fs/block_file

分片上传原理简述

API 调用方可以根据自己的需要将文件进行分片,当前支持的分片大小有 1M/2M/4M/8M/16M,然后每次请求只上传某一个分片的二进制数据。

  • 为了让服务端知道如何拼合分片成完整的文件,调用方还需要传递当前分片的索引
  • 为了让服务端知道断点续传前后上传的分片是否属于同一个文件,调用方需要在每次请求中传递整个文件的摘要(MD5)
  • 针对每次分片上传请求,服务端不仅会返回上传成功与否,还会返回当前文件还有哪些分片没有上传,便于调用方选择下一个上传的分片
  • 断点续传功能可能会在云存储中遗留未完成的文件,占据用户一定的空间,所以建议用户在遇到上传中断的情况下,及时进行续传
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

参见 全局错误码

上次修改: 2019-07-12 16:59