This topic describes how to upload local files or data to OSS objects by using simple upload and multipart upload.

Simple upload

The following code provides an example on how to call the PutObject operation to upload file objects, Blob data, or OSS buffers to OSS.

Blob indicates large binary objects. For more information, see Blob.

let OSS = require('ali-oss');

let client = new OSS({
  // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
  region: '<Your region>',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create your RAM user, log on to https://ram.console.aliyun.com.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});


// You can upload file objects, Blob data, and OSS buffers to OSS.
const data = '<File Object>‘;
// or const data = new Blob('content');
// or const data = new OSS.Buffer('content'));

async function putObject () {
  try {
    // Set object-key to an object name, such as file.txt, or a directory such as abc/test/file.txt to upload the object to the current bucket or the specified directory in the bucket.
    let result = await client.put('object-key', data);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}
putObject();

Multipart upload

To upload a large file, you can call MultipartUpload to perform multipart upload. In multipart upload, a file is divided into multiple parts for upload. If some parts fail to upload, you can continue the upload based on the recorded upload progress to upload only the parts fail to upload. We recommend that you use multipart upload to upload files larger than 100 MB to improve the upload success rate.

You must handle the ConnectionTimeoutError error by yourself when you call the MultipartUpload operation. You can handle timeout errors by reducing part size, increasing expiration period, sending the request again, or identifying ConnectionTimeoutError error messages. For more information, see Network connection timeout handling.

The following code provides an example on how to perform resumable upload by using multipart upload.

Note
  • The checkpoint parameter specifies a checkpoint file to record upload progress. To continue a resumable upload task, pass the checkpoint parameter in the request.
  • We recommend that you create a new OSS client instance when you perform multipart upload.
  • For more information about related parameters, visit GitHub.
let OSS = require('ali-oss')

let ossConfig = {
  // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
  region: '<Your region>',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create your RAM user, log on to https://ram.console.aliyun.com.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
}

let client = new OSS(ossConfig);

let tempCheckpoint;

// Define the upload method.
async function multipartUpload () {
  try {
    // Set object-key to an object name, such as file.txt, or a directory such as abc/test/file.txt to upload the object to the current bucket or the specified directory in the bucket.
    let result = await client.multipartUpload('object-key', 'file-object', { 
      progress: function (p, checkpoint) {
        // Set the checkpoint parameter. A resumable upload task cannot be automatically continued after the browser is restarted. You must manually continue the task.
        tempCheckpoint = checkpoint;
      }
      meta: { year: 2020, people: 'test' },
      mime: 'image/jpeg'
   })
  } catch(e){
    console.log(e);
  }
}

// Start the multipart upload task.
multipartUpload();

// Pause the multipart upload task.
client.cancel();

// Resume the multipart upload task.
let resumeclient = new OSS(ossConfig);
async function resumeUpload () {
  try {
    let result = await resumeclient.multipartUpload('object-key', 'file-object', {
    progress: function (p, checkpoint) {
          tempCheckpoint = checkpoint;
        },
        checkpoint: tempCheckpoint
        meta: { year: 2020, people: 'test' },
        mime: 'image/jpeg'
  })
  } catch (e) {
    console.log(e);
  }
}

resumeUpload();
			
  • progress specifies a progress callback function that is used to query the upload progress.
    const progress = function progress(p, checkpoint) {
      console.log(p)
    };
    					
  • meta specifies the user metadata. You can obtain the object metadata by using the head operation. In addition, you must configure exposed headers on the OSS console. For more information, see Configure CORS rules.

    The following figure shows the response when the request is successful.

  • You can add a callback field to the options parameter to obtain a callback for the request. The following code provides an example of the callback field:
    callback: {
      url: 'http://oss-demo.aliyuncs.com:23450',
      host: 'oss-cn-hangzhou.aliyuncs.com',
      /* eslint no-template-curly-in-string: [0] */
      body: 'bucket=${bucket}&object=${object}&var1=${x:var1}',
      contentType: 'application/x-www-form-urlencoded',
      customValue: {
        var1: 'value1',
        var2: 'value2',
      },
    },