edit-icon download-icon

Upload objects

Last Updated: Mar 06, 2018

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

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

Upload a local file

You can use the put interface to upload a local file to OSS:

  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', 'local-file');
  11. console.log(result);
  12. }).catch(function (err) {
  13. console.log(err);
  14. });

Stream upload

You can use the putStream interface to upload the content in a stream. The stream parameter can be any object that implements Readable Stream, including the object stream and network stream. When you use the putStream interface, SDK initiates a chunked encoding HTTP PUT request by default. If you specify the contentLength parameter in options, the chunked encoding is not used.

  1. var co = require('co');
  2. var OSS = require('ali-oss');
  3. var fs = require('fs');
  4. var client = new OSS({
  5. region: '<Your region>',
  6. accessKeyId: '<Your AccessKeyId>',
  7. accessKeySecret: '<Your AccessKeySecret>',
  8. bucket: 'Your bucket name'
  9. });
  10. co(function* () {
  11. // use 'chunked encoding'
  12. var stream = fs.createReadStream('local-file');
  13. var result = yield client.putStream('object-key', stream);
  14. console.log(result);
  15. // do not use 'chunked encoding'
  16. var stream = fs.createReadStream('local-file');
  17. var size = fs.statSync('local-file').size;
  18. var result = yield client.putStream(
  19. 'object-key', stream, {contentLength: size});
  20. console.log(result);
  21. }).catch(function (err) {
  22. console.log(err);
  23. });

Upload content in the buffer

You can upload the object content in the buffer to OSS through 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. The advantage of multipart upload 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 but, you can upload only the failed parts . Generally for an object larger than 100 MB, we recommend the preceding multipart upload approach.

Related parameters:

  • name {String}: Object name
  • file {String|File}: File path or HTML5 Web File
  • [options] {Object}: Optional parameter
    • [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.
    • [partSize] {Number}: Part size
    • [progress] {Funtion}: 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. });
  19. console.log(result);
  20. var head = yield client.head('object-key');
  21. console.log(head);
  22. }).catch(function (err) {
  23. console.log(err);
  24. });

The preceding progress parameter is a progress callback function used to get the upload progress. The progress parameter 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 the metadata defined by users, which can obtain the metadata of object through the head interface.

Resumable upload

Multipart upload provides the progress parameter to allow users to pass a progress callback. In the callback SDK, the proportion and checkpoint information of the currently successful uploads are used as parameters. To achieve resumable upload, you can save the checkpoint information during the upload process.

In case of errors, you can pass the saved checkpoint as parameters to multipartUpload and the upload resumes from the last failed part.

  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 checkpoint;
  11. // retry 5 times
  12. for (var i = 0; i < 5; i++) {
  13. var result = yield client.multipartUpload('object-key', 'local-file', {
  14. checkpoint: checkpoint,
  15. progress: function* (percentage, cpt) {
  16. checkpoint = cpt;
  17. }
  18. });
  19. console.log(result);
  20. break; // break if success
  21. } catch (err) {
  22. console.log(err);
  23. }
  24. }
  25. }).catch(function (err) {
  26. console.log(err);
  27. });

The preceding code saves the checkpoint in the variable. If the program crashes, the information is lost. You can save information in an object and read the checkpoint information from the object after the project gets restarted.

Thank you! We've received your feedback.