上传文件

上传Blob数据

Blob (Binary Large Object) 代表二进制类型的大对象。在一些数据库中会使用到Blob的概念。例如MySQL中的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) {
    console.log(e);
  }
}
putBlob();
			

断点续传上传

当需要上传的文件较大时，可以通过MultipartUpload接口进行分片上传。分片上传的好处是将一个大请求分成多个小请求来执行。这样当其中一些分片请求失败后，保留上传进度记录，再次重传时只需要上传失败的分片，而不需要重新上传整个文件。一般对于大于100MB的文件，建议采用分片上传的方法，通过断点续传和重试，提高上传成功率。

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

相关参数说明如下：

• name {String} Object名称。
• file {File} HTML5网络文件或file {Blob} 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请求和响应中，通过指定指令来实现缓存机制， 例如Cache-Control: public, no-cache。
    • 'Content-Disposition' 指定回复的内容该以何种形式展示。是以内联的形式（即网页或者页面的一部分），还是以附件的形式下载并保存到本地，例如Content-Disposition: somename。
    • 'Content-Encoding' 用于对特定媒体类型的数据进行压缩， 例如Content-Encoding: gzip。
    • 'Expires' 过期时间，例如Expires: 3600000。
  • [callback] {Object} callback回调设置。
    • url {String} 和oss server交互的回调服务器地址，对应CallBack参数中的callbackUrl。
    • body {String} 发起回调时请求body的值，对应CallBack参数中的callbackBody。body值为JSON格式。
    • [host] {String} 发起回调请求时Host头的值，对应CallBack参数中的callbackHost。
    • [contentType] {String} 发起回调请求的Content-Type，对应CallBack参数中的callbackBodyType。
    • [customValue] {Object} 发起回调请求自定义参数，对应CallBack参数中的callback-var。

以下代码用于断点续传上传：

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 function multipartUpload () {
  try {
    let result = await client.multipartUpload('object-key', 'local-file', { 
      progress: async function (p, checkpoint) {
        // 断点记录点。 浏览器重启后无法直接继续上传，需用户手动触发进行设置。
        tempCheckpoint = checkpoint;
      }
      meta: { year: 2017, people: 'test' },
      mime: 'image/jpeg'
   })
  } 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
        meta: { year: 2017, people: 'test' },
        mime: 'image/jpeg'
  })
  } catch (e) {
    console.log(e);
  }
}

resumeUpload();
			

上述示例中的progress参数是一个进度回调函数，用于获取上传进度。

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

meta参数是一个用户自定义的元数据，通过head接口可以获取到Object的meta数据。您需要在OSS控制台基础设置页签下的跨域设置中设置暴露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',
  },
},