阿里雲團隊努力不懈,力求將最新的技術內容更快地以您最熟悉的語言呈現。本文由簡體中文內容自動轉碼而成,過程無人工干預。阿里雲不保證此自動轉碼的準確性、完整性及時效性。因轉碼造成的任何內容錯誤及因此可能帶來的損失,阿里雲概不負責,敬請見諒。本文内容請以簡體中文版本為準。
全部產品
Search
文件中心

上傳檔案

更新時間: Oct 30, 2018

使用者可以通過以下方式向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 ,它是區分分區上傳事件的唯一標識,在後面的操作中,我們將用到它。