上传文件_Browser.js_SDK 参考_对象存储 OSS-阿里云

本文介绍如何上传文件。

用户可以通过以下方式向OSS中上传文件：

上传本地文件
上传blob数据
分片上传
暂停分片上传

上传本地文件

请直接参考分片上传

上传Blob数据

用户也可以通过put接口简单地将Blob中的内容上传到OSS：

let OSS = require('ali-oss');

let client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});

async function putBlob () {
  try {
    let result = await client.put('object-key', new Blob(['content'],{ type: 'text/plain' }));
    console.log(result);
  } catch (e) {
    conosle.log(e);
  }
}
putBlob();

分片上传

在需要上传的文件较大时，可以通过multipartUpload接口进行分片上传。分片上传的好处是将一个大请求分成多个小请求来执行，这样当其中一些请求失败后，不需要重新上传整个文件，而只需要上传失败的分片就可以了。一般对于大于100MB的文件，建议采用分片上传的方法，每次进行分片上传都建议重新new一个新的OSS实例。

在使用multipartUpload接口如果遇到ConnectionTimeoutError超时问题，业务方需要自己处理超时逻辑。如何处理超时，可以缩小分片大小、加大超时时间、重试请求，或者业务上捕获ConnectionTimeoutError错误，然后给用户提示。

阿里云分片上传流程主要会调用3个api，包含 1. InitiateMultipartUpload, 分片任务初始化接口。 2. UploadPart,单独的分片上传接口。 3. CompleteMultipartUpload,分片上传完成后任务完成接口。各个api的使用方式会在后续介绍，具体内容参见MultipartUpload。

相关参数：

name {String} object 名称
file {File|Blob} HTML5 Web File or Blob的数据格式
[options] {Object} 额外参数
- [checkpoint] {Object} 断点记录点，可以进行断点续传, 如果设置这个参数，上传会从断点开始，如果没有设置，就会重新上传.
  - file {File} 用户选取的文件对象，如果浏览器重启后这个需要用户手动触发进行设置
  - name {String} 上传的object key
  - fileSize {Number} 文件大小
  - partSize {Number} 分片大小
  - uploadId {String} 分片上传的ID
  - doneParts {Array} 已完成的分片的数组, 包含的对象结构如下
    - number {Number} 分片的number
    - etag {String} 分片的etag
- [parallel] {Number} 并发上传的分片个数
- [partSize] {Number} 分片大小
- [progress] {Function} function、 async 、promise 形式, 回调函数包含三个参数
  - (percentage {Number} 进度百分比(0-1之间小数)
  - checkpoint {Object} 断点记录点
  - res {Object}) 单次part成功返回的response
- [meta] {Object} 用户自定义header meta信息, header前缀 x-oss-meta-
- [mime] {String} 用户自定义 Content-Type header
- [headers] {Object} http 额外的头字段, 详情请看 RFC 2616
  - 'Cache-Control' 通用消息头被用于在http 请求和响应中通过指定指令来实现缓存机制, e.g.: Cache-Control: public, no-cache
  - 'Content-Disposition' 指示回复的内容该以何种形式展示，是以内联的形式（即网页或者页面的一部分），还是以附件的形式下载并保存到本地, e.g.: Content-Disposition: somename
  - 'Content-Encoding' 用于对特定媒体类型的数据进行压缩, e.g.: Content-Encoding: gzip
  - 'Expires' 过期时间, e.g.: Expires: 3600000
- [callback] {Object} callback回调设置。具体内容参见Callback：
  - url {String} 和oss server交互的回调服务器地址。对应于CallBack参数中的callbackUrl。必须有。
  - body {String} 发起回调时请求body的值。jason格式。对应于CallBack参数中的callbackBody。必须有。
  - [host] {String} 发起回调请求时Host头的值。对应于CallBack参数中的callbackHost。
  - [contentType] {String} 发起回调请求的Content-Type。对应于CallBack参数中的callbackBodyType 。
  - [customValue] {Object} 发起回调请求自定义参数。对应于CallBack参数中的callback-var。

范例：

let OSS = require('ali-oss')

let client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});

async function multipartUpload () {
  try {
    let result = await client.multipartUpload('object-key', 'local-file', {
    progress: async function (p) {
      console.log('Progress: ' + p);
    },
	meta: {
	  year: 2017,
	  people: 'test'
	},
	mime: 'image/jpeg'
  });
  console.log(result);
  let head = await client.head('object-key');
  console.log(head);
  } catch (e) {
    // 捕获超时异常
	if (e.code === 'ConnectionTimeoutError') {
	  console.log("Woops,超时啦!");
	  // do ConnectionTimeoutError operation
	}
    console.log(e);
  }
}

上面的progress参数是一个进度回调函数，用于获取上传进度

const progress = async function progress(p, checkpoint) {
  console.log(p)
};

上面的 meta参数是一个用户自定义的元数据，通过head接口可以获取到object的meta数据，但是这个meta header 需要在控制台跨域设置里边的暴露header中设置好，如图：

请求成功后的返回结果展示:

上面的上传回调通知具体使用可以在options参数中添加 callback，代码如下：

callback: {
  url: 'http://oss-demo.aliyuncs.com:23450',
  host: 'oss-cn-hangzhou.aliyuncs.com',
  /* eslint no-template-curly-in-string: [0] */
  body: 'bucket=${bucket}&object=${object}&var1=${x:var1}',
  contentType: 'application/x-www-form-urlencoded',
  customValue: {
    var1: 'value1',
    var2: 'value2',
  },
},

.initMultipartUpload(name[, options])

initiateMultipartUpload 的返回结果中含有UploadId ，它是区分分片上传事件的唯一标识，在分片上传后续的的操作中，我们都会用到它。

.uploadPart(name, uploadId, partNo, file, start, end[, options])

uploadPart是分片上传的核心接口,有以下要点需要注意：

UploadPart 方法要求除最后一个Part以外，其他的Part大小都要大于100KB。但是Upload Part接口并不会立即校验上传Part的大小（因为不知道是否为最后一块）；只有当Complete Multipart Upload的时候才会校验。
OSS会将服务器端收到Part数据的MD5值放在ETag头内返回给用户。
Part号码的范围是1~10000。如果超出这个范围，OSS将返回InvalidArgument的错误码。
每次上传part时都要把流定位到此次上传片开头所对应的位置。
每次上传part之后，OSS的返回结果会包含一个分片的ETag，您需要将它和块编号组合成PartEtag，保存在list中，后续完成分片上传需要用到。

暂停分片上传

分片上传暂停后，恢复上传时需要将之前记录的checkpoint参数传入即可.
每次进行分片上传建议重新new一个新的OSS实例.

let OSS = require('ali-oss')

let ossConfig = {
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
}

let client = new OSS(ossConfig);

let tempCheckpoint;

// 定义上传方法
async funtion multipartUpload () {
  try {
    let result = await client.multipartUpload('object-key', 'local-file', { progress: async function (p, checkpoint) {
	  // 记录断点, 如果关闭了浏览器，然后重新启动继续上传的话，是不行的，请参考上边对file对象的描述
      tempCheckpoint = checkpoint;
    }
   })
  } catch(e){
    console.log(e);
  }
}

//开始上传
multipartUpload();

// 暂停分片上传方法
client.cancel();

// 恢复上传
let resumeclient = new OSS(ossConfig);
async function resumeUpload () {
  try {
    let result = await resumeclient.multipartUpload('object-key', 'local-file', {
	progress: async function (p, checkpoint) {
      tempCheckpoint = checkpoint;
    },
	checkpoint: tempCheckpoint
  })
  } catch (e) {
    console.log(e);
  }
}

resumeUpload();

我们用InitiateMultipartUploadRequest来指定上传文件的名字和所属存储空间（Bucket）。在InitiateMultipartUploadRequest中，您也可以设置ObjectMeta，但是不必指定其中的ContentLength 。 initiateMultipartUpload 的返回结果中含有UploadId ，它是区分分片上传事件的唯一标识，在后面的操作中，我们将用到它。