全部产品
阿里云办公

上传文件

更新时间:2018-07-24 14:43:49

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

上传本地文件

请直接参考分片上传

上传Buffer内容

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

  1. let OSS = require('ali-oss');
  2. let client = new OSS({
  3. region: '<Your region>',
  4. accessKeyId: '<Your AccessKeyId>',
  5. accessKeySecret: '<Your AccessKeySecret>',
  6. bucket: 'Your bucket name'
  7. });
  8. async function put () {
  9. try {
  10. let result = await client.put('object-key', new Buffer('hello world'));
  11. console.log(result);
  12. } catch (e) {
  13. console.log(e);
  14. }
  15. }
  16. put();

上传Blob数据

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

  1. let OSS = require('ali-oss');
  2. let client = new OSS({
  3. region: '<Your region>',
  4. accessKeyId: '<Your AccessKeyId>',
  5. accessKeySecret: '<Your AccessKeySecret>',
  6. bucket: 'Your bucket name'
  7. });
  8. async function putBlob () {
  9. try {
  10. let result = await client.put('object-key', new Blob(['content'],{ type: 'text/plain' }));
  11. console.log(result);
  12. } catch (e) {
  13. conosle.log(e);
  14. }
  15. }
  16. 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} functionasyncpromise 形式, 回调函数包含三个参数
      • (percentage {Number} 进度百分比(0-1之间小数)
      • checkpoint {Object} 断点记录点
      • res {Object}) 单次part成功返回的response
    • [meta] {Object} 用户自定义header meta信息, header前缀 x-oss-meta-
    • [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。

范例:

  1. let OSS = require('ali-oss')
  2. let client = new OSS({
  3. region: '<Your region>',
  4. accessKeyId: '<Your AccessKeyId>',
  5. accessKeySecret: '<Your AccessKeySecret>',
  6. bucket: 'Your bucket name'
  7. });
  8. async function multipartUpload () {
  9. try {
  10. let result = await client.multipartUpload('object-key', 'local-file', {
  11. progress: async function (p) {
  12. console.log('Progress: ' + p);
  13. },
  14. meta: {
  15. year: 2017,
  16. people: 'test'
  17. },
  18. mime: 'image/jpeg'
  19. });
  20. console.log(result);
  21. let head = await client.head('object-key');
  22. console.log(head);
  23. } catch (e) {
  24. // 捕获超时异常
  25. if (e.code === 'ConnectionTimeoutError') {
  26. console.log("Woops,超时啦!");
  27. // do ConnectionTimeoutError operation
  28. }
  29. console.log(e);
  30. }
  31. }

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

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

上面的meta参数是一个用户自定义的元数据,通过head接口可以获取到object的meta数据,但是这个meta header 需要在控制台跨域设置里边的暴露header中设置好,如图:meta 设置请求成功后的返回结果展示:结果展示

.initMultipartUpload(name[, options])

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

相关参数:

  • name {String} object 名称
  • [options] {Object} 额外参数
    • [timeout] {Number} 超时设置
    • [mime] 上传文件类型。例如: application/octet-stream
    • [meta] {Object} 用户自定义header meta信息, header前缀 ‘x-oss-meta-‘
    • [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;
      • [x-oss-server-side-encryption] 只需要请求中携带x-oss-server-side-encryption的HTTP Header,并指定其值为AES256,即可以实现该Object的服务器端加密存储

请求成功返回内容:

  • res {Object} 返回内容,包括
    • status {Number} 返回状态码
    • headers {Object} 返回的头信息
    • size {Number} 返回内容的长度
    • rt {Number} 请求耗时 (ms)
  • bucket {String} bucket 名称
  • name {String} 储存在oss的object名称
  • uploadId {String} upload id 分片上传任务id

范例

  1. let result = await store.initMultipartUpload('object');
  2. console.log(result);

.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中,后续完成分片上传需要用到。

相关参数:

  • name {String} object 名称
  • uploadId {String} 分片上传任务id
  • partNo {Number} 分片序列号
  • file {File} 整个上传文件对象
  • start {Number} 分片在文件的启始位置,单位字节 e.g: 102400
  • end {Number} 分片在文件的结束位置,单位字节 e.g: 204800
  • [options] {Object} 额外参数
    • [timeout] {Number} 超时设置

请求成功后的返回结果:

  • res {Object} 返回内容,包括
    • status {Number} 返回状态码
    • headers {Object} 返回的头信息
    • size {Number} 返回内容的长度
    • rt {Number} 请求耗时 (ms)
  • bucket {String} bucket 名称
  • name {String} 储存在oss的object名称
  • etag {String} part etag 内容e.g.: “5B3C1A2E053D763E1B002CC607C5A0FE”。后续交验需要。

范例:

  1. let name = 'object';
  2. let result = await store.initMultipartUpload(name);
  3. let uploadId = result.uploadId;
  4. let file; //the data you want to upload, is a File or FileName(only in node)
  5. //if file part is 10
  6. let partSize = 100 * 1024;
  7. let fileSize = 10 * partSize;//you need to calculate
  8. let dones = [];
  9. for (let i = 1; i <= 10; i++) {
  10. let start = partSize * (i -1);
  11. let end = Math.min(start + partSize, fileSize);
  12. let part = await store.uploadPart(name, uploadId, i, file, start, end);
  13. dones.push({
  14. number: i,
  15. etag: part.etag
  16. });
  17. console.log(part);
  18. }
  19. //end need to call completeMultipartUpload api

completeMultipartUpload(name, uploadId, parts[, options])

在将所有数据Part都上传完成后,必须调用Complete Multipart Upload API来完成整个文件的Multipart Upload。在执行该操作时,用户必须提供所有有效的数据Part的列表(包括part号码和ETAG);OSS收到用户提交的Part列表后,会逐一验证每个数据Part的有效性。当所有的数据Part验证通过后,OSS将把这些数据part组合成一个完整的Object。

相关参数:

  • name {String} object 名称
  • uploadId {String} 分片上传任务id
  • parts {Array} 有效的数据Part的列表(包括分片序列号和ETAG):
    • number {Number} 分片序列号
    • etag {String} object etag “, e.g.: “5B3C1A2E053D763E1B002CC607C5A0FE”
    • [options] {Object} 额外参数
      • [timeout] {Number} 超时设置
      • [headers] {Object} 更多头信息, 详见 RFC 2616
      • [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。

请求成功后的返回结果:

  • res {Object} 返回内容,包括
    • status {Number} 返回状态码
    • headers {Object} 返回的头信息
    • size {Number} 返回内容的长度
    • rt {Number} 请求耗时 (ms)
  • bucket {String} bucket 名称
  • name {String} 储存在oss的object名称
  • etag {String} 上传文件的 etag 内容e.g.: “5B3C1A2E053D763E1B002CC607C5A0FE”。
  • data {Object} 回调服务器返回内容。
  1. //init multipart
  2. let name = 'object';
  3. try {
  4. let result = await store.initMultipartUpload(name);
  5. } catch (e) {
  6. console.log(e);
  7. }
  8. //upload part
  9. let file; //the data you want to upload, this example size is 10 * 100 * 1024
  10. let fileSize;//you need to calculate
  11. let partSize = 100 * 1024;//100kb
  12. let done = [];
  13. //if file part is 10
  14. for (var i = 1; i <= 10; i++) {
  15. let start = partSize * (i -1);
  16. let end = Math.min(start + partSize, fileSize);
  17. let data = file.slice(start, end);
  18. try {
  19. let part = await store.uploadPart(name, result.uploadId, i, data);
  20. } catch (e) {
  21. console.log(e);
  22. }
  23. console.log(part);
  24. done.push({
  25. number: i,
  26. etag: part.res.headers.etag
  27. });
  28. }
  29. //complete
  30. let completeData = await store.completeMultipartUpload(name, result.uploadId, done);
  31. console.log(completeData);

暂停分片上传

  1. 分片上传暂停后,恢复上传时需要将之前记录的checkpoint参数传入即可.
  2. 每次进行分片上传建议重新new一个新的OSS实例.
  1. let OSS = require('ali-oss')
  2. let ossConfig = {
  3. region: '<Your region>',
  4. accessKeyId: '<Your AccessKeyId>',
  5. accessKeySecret: '<Your AccessKeySecret>',
  6. bucket: 'Your bucket name'
  7. }
  8. let client = new OSS(ossConfig);
  9. let tempCheckpoint;
  10. // 定义上传方法
  11. async funtion multipartUpload () {
  12. try {
  13. let result = await client.multipartUpload('object-key', 'local-file', { progress: async function (p, checkpoint) {
  14. // 记录断点, 如果关闭了浏览器,然后重新启动继续上传的话,是不行的,请参考上边对file对象的描述
  15. tempCheckpoint = checkpoint;
  16. }
  17. })
  18. } catch(e){
  19. console.log(e);
  20. }
  21. }
  22. //开始上传
  23. multipartUpload();
  24. // 暂停分片上传方法
  25. client.cancel();
  26. // 恢复上传
  27. let resumeclient = new OSS(ossConfig);
  28. async function resumeUpload () {
  29. try {
  30. let result = await resumeclient.multipartUpload('object-key', 'local-file', {
  31. progress: async function (p, checkpoint) {
  32. tempCheckpoint = checkpoint;
  33. },
  34. checkpoint: tempCheckpoint
  35. })
  36. } catch (e) {
  37. console.log(e);
  38. }
  39. }
  40. resumeUpload();

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

本文导读目录