edit-icon download-icon

Upload objects

Last Updated: Nov 30, 2018

You can upload a file to OSS using any of the following methods:

  • Upload a local file
  • Upload content in the buffer
  • Multipart upload

Upload local files

See Multipart Upload

Upload content in the buffer

You can also upload the object content in the buffer to the OSS using the put interface:

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

Multipart upload

When the file to be uploaded is large, you can use the multipartUpload interface for multipart upload. Multipartupload is to divide a large request into multiple small requests for execution. As a result, when some of the requests fail,you do not need to upload the entire file again, but only to upload the failed parts. Generally for a file larger than100 MB, we recommend that you use the preceding multipart upload approach and create a new OSS instance before each multipart upload.Related parameters:

  • name {String}: Object name
  • file {File}: HTML5 Web File
  • [options] {Object}: Additional parameters
    • [checkpoint] {Object}: Endpoint checkpoint used in resumable upload. If this parameter is set, the upload starts from the endpoint. If it is not set, the upload restarts.
    • file {File}: File object selected by the user. Users must manually set this parameter if the browser is restarted.
      • name {String}: Uploaded object key
      • fileSize {Number}: File size
      • partSize {Number}: Part size
      • uploadId {String}: Upload Id
      • doneParts {Array}: Array of uploaded parts, including the following objects:
        • number {Number}: Part number
        • etag {String}: Part etag
    • [partSize] {Number}: Part size
      • [progress] {Function}: A generator function or a thunk. The callback function contains the following three parameters:
      • (percentage {Number}: Percetage of upload progress (a decimal range from 0 to 1)
      • checkpoint {Object}: Endpoint checkpoint
      • res {Object}): Response returned after a single part is successfully uploaded
    • [meta] {Object}: Header meta inforamtion defined by users with a prefix x-oss-meta-
    • [headers] {Object}: Extra headers. See RFC 2616 for more information.
      • ‘Cache-Control’: General header used to implement cache mechanisms by specifying a command in HTTP requests and responses. For example: Cache-Control: public, no-cache
      • ‘Content-Disposition’: Used to indicate the disposition form of a response, which can be an internal reference (a part of a webpage or a page) or an attachment downloaded and saved locally. For example: Content-Disposition: somename
      • ‘Content-Encoding’: Used to compress data of specific media type. For example: Content-Encoding: gzip
      • ‘Expires’: Expiration time. For example: Expires: 3600000
  1. var co = require('co');
  2. var OSS = require('ali-oss')
  3. var client = new OSS({
  4. region: '<Your region>',
  5. accessKeyId: '<Your AccessKeyId>',
  6. accessKeySecret: '<Your AccessKeySecret>',
  7. bucket: 'Your bucket name'
  8. });
  9. co(function* () {
  10. var result = yield client.multipartUpload('object-key', 'local-file', {
  11. progress: 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. var head = yield client.head('object-key');
  22. console.log(head);
  23. }).catch(function (err) {
  24. console.log(err);
  25. });

The preceding progress parameter is a progress callback function used to get the upload progress. The progressparameter can be a generator function (function*`), or a “thunk”:

  1. var progress = function (p) {
  2. return function (done) {
  3. console.log(p);
  4. done();
  5. };
  6. };

The preceding meta parameter is a user-defined metadata. You can obtain the meta value of the object using the head API, but the meta header must be set properly in the Exposed Headers of the Cross-region Settings in the console, as shown in the following figure:


meta-setting

Returned results of successful requests:


oss-returned-results

Pause the multipart upload

  1. Before resuming the paused multipart upload, you must pass the checkpoint parameter recorded when the upload is paused.
  2. We recommend you create a new OSS instance before each multiple upload.
  1. var co = require('co');
  2. var OSS = require('ali-oss')
  3. var ossConfig = {
  4. region: '<Your region>',
  5. accessKeyId: '<Your AccessKeyId>',
  6. accessKeySecret: '<Your AccessKeySecret>',
  7. bucket: 'Your bucket name'
  8. }
  9. var client = new OSS(ossConfig);
  10. var tempCheckpoint;
  11. co(function* () {
  12. var result = yield client.multipartUpload('object-key', 'local-file', {
  13. progress: function* (p, checkpoint) {
  14. // Record the checkpoint
  15. tempCheckpoint = checkpoint;
  16. }
  17. })
  18. }
  19. // Method of pausing the multipart upload
  20. client.cancel();
  21. // Resume the upload
  22. var resumeclient = new OSS(ossConfig);
  23. co(function* () {
  24. var result = yield resumeclient.multipartUpload('object-key', 'local-file', {
  25. progress: function* (p, checkpoint) {
  26. tempCheckpoint = checkpoint;
  27. },
  28. checkpoint: tempCheckpoint
  29. })
  30. }
Thank you! We've received your feedback.