本文档介绍如何使用分片上传。

说明 以下示例代码中的 catch 语法,请自行学习 es6 promise、async/await。 SDK的使用方式,请参考安装

当需要上传的文件较大时,可以通过MultipartUpload接口进行分片上传。分片上传是指将要上传的文件分成多个数据块(OSS里又称之为Part)来分别上传。当其中一些分片上传失败后,OSS将保留上传进度记录,再次重传时只需要上传失败的分片,而不需要重新上传整个文件。一般对于大于100MB的文件,建议采用分片上传的方法,通过断点续传和重试,提高上传成功率。

在使用MultipartUpload接口时,如果遇到ConnectionTimeoutError超时问题,业务方需自己处理超时逻辑。例如通过缩小分片大小、加大超时时间、重试请求或者业务上捕获ConnectionTimeoutError错误等方法处理超时,详情请参见网络错误处理

相关参数说明如下:

类型 参数 说明
必选参数 name {String} 填写object名称。
file {String|File} 表示文件路径或者HTML5文件。
[options] {Object} 可选参数 [checkpoint] {Object} 记录本地分片上传结果的文件。开启断点续传功能时需要设置此参数,上传过程中的进度信息会保存在该文件中,如果某一分片上传失败,再次上传时会根据文件中记录的点继续上传。上传完成后,该文件会被删除。
[parallel] {Number} 并发上传的分片个数,默认为5。无特殊需求,不需要手动设置此参数。
[partSize] {Number} 指定上传的每个分片的大小,范围为100KB~5GB。单个分片默认大小为1 * 1024 * 1024(即1MB)。无特殊需求,不需要手动设置此参数。
[progress] {Function} 表示进度回调函数,用于获取上传进度,可以是async的函数形式。回调函数包含三个参数:
  • percentage {Number}:进度百分比(0-1之间小数)。
  • checkpoint {Object}:与[options] {Object} 中的[checkpoint] {Object}定义相同。
  • res {Object}:单个分片上传成功返回的response。
[meta] {Object} 用户自定义的 header meta 信息,header前缀为x-oss-meta-
[mime] {String} 设置Content-Type请求头。
[headers] {Object} 其他 headers,详情请参见RFC 2616。其中:
  • 'Cache-Control':通用消息头被用在 http 请求和响应中通过指定指令来实现缓存机制,例如Cache-Control: public, no-cache
  • 'Content-Disposition':指示回复的内容该以何种形式展示,是以网页预览的形式,还是以附件的形式下载并保存到本地,例如Content-Disposition: somename
  • 'Content-Encoding':用于对特定媒体类型的数据进行压缩,例如Content-Encoding: gzip
  • 'Expires':过期时间,单位为毫秒,例如Expires: 3600000

以下代码用于分片上传:

let OSS = require('ali-oss')

let client = new OSS({
  // region以杭州为例(oss-cn-hangzhou),其他region按实际情况填写。
  region: '<Your region>',
  // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: '<Your bucket name>',
});

//开始分片上传。
async function multipartUpload () {
  try {
    //object-name可以自定义为文件名(例如file.txt)或目录(例如abc/test/file.txt)的形式,实现将文件上传至当前Bucket或Bucket下的指定目录。
    let result = await client.multipartUpload('object-name', 'file-object', {
    progress,
    //meta是用户自定义的元数据,通过head接口可以获取到object的meta数据。
    meta: {
      year: 2020,
      people: 'test'
    }
  });
  console.log(result);
  let head = await client.head('object-name');
  console.log(head);
  } catch (e) {
   // 捕获超时异常。
    if (e.code === 'ConnectionTimeoutError') {
      console.log("TimeoutError");
      // do ConnectionTimeoutError operation
    }
    console.log(e)
  }
}