上傳檔案 - Object Storage Service

使用者可以通過以下方式向OSS中上傳檔案：

以下範例程式碼中的catch文法，請自行學習下es6 promise、async/await。仔細閱讀下sdk的使用方式，傳送門。

上傳本地檔案
流式上傳
上傳Buffer內容
分區上傳
斷點上傳

上傳本地檔案

通過put介面來上傳一個本地檔案到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 put () {
  try {
    let result = await client.put('object-key', 'local-file');
    console.log(result);
  } catch (e) {
      console.log(er);
  }
}
put();

流式上傳

通過putStream介面來上傳一個Stream中的內容，stream參數可以是任何實現了Readable Stream的對象，包含檔案流，網路流等。當使用putStream介面時，SDK預設會發起一個chunked encoding的HTTP PUT請求。如果在options指定了contentLength參數，則不會使用chunked encoding。

let OSS = require('ali-oss');
let fs = require('fs');
let client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
async function putStream () {
  try {
  // use 'chunked encoding'
  let stream = fs.createReadStream('local-file');
  let result = yield client.putStream('object-key', stream);
  console.log(result);
  // don't use 'chunked encoding'
  let stream = fs.createReadStream('local-file');
  let size = fs.statSync('local-file').size;
  let result = await client.putStream(
    'object-key', stream, {contentLength: size});
  console.log(result);
  } catch (e) {
    console.log(e)
  }
}
putStream();

上傳Buffer內容

使用者也可以通過put介面簡單地將Buffer中的內容上傳到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 putBuffer () {
  try {
    let result = await client.put('object-key', new Buffer('hello world'));
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}
putBuffer();

分區上傳

在需要上傳的檔案較大時，可以通過multipartUpload介面進行分區上傳。分區上傳的好處是將一個大請求分成多個小請求來執行，這樣當其中一些請求失敗後，不需要重新上傳整個檔案，而只需要上傳失敗的分區就可以了。一般對於大於100MB的檔案，建議採用分區上傳的方法。

在使用multipartUpload介面如果遇到ConnectionTimeoutError逾時問題，業務方需要自己處理逾時邏輯。如何處理逾時，可以縮小分區大小、加大逾時時間、重試請求，或者業務上捕獲ConnectionTimeoutError錯誤，然後給使用者提示。

相關參數：

name {String} object 名稱
file {String|File} file path or HTML5 Web File
[options] {Object} 額外參數
- [checkpoint] {Object} 斷點記錄點，可以進行斷點續傳, 如果設定這個參數，上傳會從斷點開始，如果沒有設定，就會重新上傳.
- [parallel] {Number} 並發上傳的分區個數
- [partSize] {Number} 分區大小
- [progress] {Function} async函數形式, 回呼函數包含三個參數
  - (percentage {Number} 進度百分比(0-1之間小數)
  - checkpoint {Object} 斷點記錄點
  - res {Object}) 單次part成功返回的response
- [meta] {Object} 使用者自訂header meta資訊, header首碼 x-oss-meta-
- [headers] {Object} extra headers, detail see 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

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,
    meta: {
      year: 2017,
      people: 'test'
    }
  });
  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參數是一個進度回呼函數，用於獲取上傳進度。progress可以是一個async函數：

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

上面的meta參數是一個使用者自訂的元資料，通過head介面可以獲取到object的meta資料。

斷點上傳

分區上傳提供progress參數允許使用者傳遞一個進度回調，在回調中SDK將當前已經上傳成功的比例和斷點資訊作為參數。為了實現斷點上傳，可以在上傳過程中保存斷點資訊（checkpoint），發生錯誤後，再將已保存的checkpoint作為參數傳遞給multipartUpload，此時將從上次失敗的地方繼續上傳。

let OSS = require('ali-oss');
let client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
let checkpoint;
async function resumeUpload() {
  // retry 5 times
  for (let i = 0; i < 5; i++) {
    try {
      const result = await client.multipartUpload('object-key', filePath, {
        checkpoint,
        async progress(percentage, cpt) {
          checkpoint = cpt;
        },
      });
      console.log(result);
      break; // break if success
    } catch (e) {
      console.log(e);
    }
  }
}
resumeUpload();

上面的代碼只是將checkpoint保存在變數中，如果程式崩潰的話就丟失了，使用者也可以將它保存在檔案中，然後在程式重啟後將checkpoint資訊從檔案中讀取出來。