By using the multipart upload feature provided by OSS, you can split a large object into multiple parts and upload them separately. After all parts are uploaded, call the CompleteMultipartUpload operation to combine these parts into a single object to implement resumable upload.

Background information

To upload a large object, you can call MultipartUpload to perform multipart upload. In multipart upload, a local file is split into multiple parts. Then, separately upload the parts. If some parts fail to upload, you can continue the upload based on the recorded upload progress to upload only the parts that fail to upload. To upload an object larger than 100 MB, we recommend that you use multipart upload. This improves the upload success rate.

If the ConnectionTimeoutError occurs when you call the MultipartUpload operation, you must fix the error on your own. To fix the error, you can reduce the size of each part, extend the timeout period, or resend the request. You can also capture ConnectionTimeoutError to analyze the specific cause. For more information, see Network connection timeout handling.

The following table describes the parameters that you can configure when you use Object Storage Service (OSS) SDK for Node.js to upload objects by using multipart upload.

Type Parameter Description
Required parameter name {String} The full path of the object, which cannot contain the bucket name.
file {String|File} The path of the local file or HTML5 file to upload.
[options] {Object} Optional parameters [checkpoint] {Object} The checkpoint file that records the result of the multipart upload task. You must set this parameter if you want to perform resumable upload by using multipart upload. The checkpoint file stores the progress information about a multipart upload task. If a part fails to upload, the task can be continued based on the progress recorded in the checkpoint file. After you have uploaded the local file, the checkpoint file is deleted.
[parallel] {Number} The number of parts that can be concurrently uploaded. Default value: 5. Do not modify the value of this parameter unless necessary.
[partSize] {Number} The size of each part to upload. Valid values: 100 KB to 5 GB. Default value: 1 MB. Do not modify the value of this parameter unless necessary.
[progress] {Function} The callback function used to query the progress of the upload task. The callback function can be an async function. The callback function includes the following parameters:
  • percentage {Number}: the progress of the upload task in percentage. Valid values: decimals between 0 and 1.
  • checkpoint {Object}: the checkpoint file that records the result of multipart upload.
  • res {Object}: the response returned when a part is uploaded.
[meta] {Object} The user metadata, which is prefixed with x-oss-meta.
[mime] {String} The Content-Type request header.
[headers] {Object} Other headers. For more information, see RFC 2616. Examples:
  • Cache-Control: specifies the caching behavior by using specified commands in HTTP requests or responses. Example: Cache-Control: public, no-cache.
  • Content-Disposition: specifies whether the returned content is displayed as a web page or downloaded as an attachment. Example: Content-Disposition: somename.
  • Content-Encoding: the method to compress data of the specified media type. Example: Content-Encoding: gzip.
  • Expires: the validity period of the request. Unit: milliseconds.

Complete sample code

The following code provides a complete example that describes the process of multipart upload:

Notice OSS SDK for Node.js does not support MD5 verification in multipart upload tasks. We recommend that you call the CRC64 library to determine whether to perform CRC-64 checks after the multipart upload task is completed.
const OSS = require('ali-oss');
const path = require("path");

const client = new OSS({
  // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
  region: 'yourRegion',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a Resource Access Management (RAM) user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket to which you want to upload the object. Example: examplebucket. 
  bucket: 'examplebucket',
});


const progress = (p, _checkpoint) => {
  console.log(p); // The upload progress of the object. 
  console.log(_checkpoint); // The checkpoint information of the multipart upload task. 
};

// Start the multipart upload task. 
async function multipartUpload() {
  try {
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. Then, specify the full path of the local file. Example: D:\\localpath\\examplefile.txt. The full path of the object cannot contain the bucket name. 
    // By default, if you set this parameter to the name of a local file such as examplefile.txt without specifying the local path, the local file is uploaded from the local path of the project to which the sample program belongs. 
    const result = await client.multipartUpload('exampledir/exampleobject.txt', path.normalize('D:\\localpath\\examplefile.txt'), {
      progress,
      // Specify the meta parameter to set custom object metadata for the object. You can call the HeadObject operation to obtain the object metadata. 
      meta: {
        year: 2020,
        people: 'test',
      },
    });
    console.log(result);
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    const head = await client.head('exampledir/exampleobject.txt');
    console.log(head);
  } catch (e) {
    // Handle timeout exceptions. 
    if (e.code === 'ConnectionTimeoutError') {
      console.log('TimeoutError');
      // do ConnectionTimeoutError operation
    }
    console.log(e);
  }
}

multipartUpload();

Cancel a multipart upload task

You can call client.AbortMultipartUpload to cancel a multipart upload task. If you cancel a multipart upload task, you cannot use the upload ID to upload parts. The uploaded parts are deleted.

The following code provides an example on how to cancel a multipart upload task:

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

const client = new OSS({
  // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
  region: 'yourRegion',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket to which you want to upload the object. Example: examplebucket. 
  bucket: 'examplebucket',
});

async function abortMultipartUpload() {
  // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
  const name = 'exampledir/exampleobject.txt';
  // Specify the upload ID. The upload ID is obtained from the information returned by the multipart upload task. 
  const uploadId = '0004B999EF518A1FE585B0C9360D****'; 
  const result = await client.abortMultipartUpload(name, uploadId);
  console.log(result);
}

abortMultipartUpload();

List multipart upload tasks

You can use the client.listUploads method to list all ongoing multipart upload tasks. Ongoing multipart upload tasks include tasks that have been initiated but not completed and tasks that have been canceled.

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

const client = new OSS({
  // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
  region: 'yourRegion',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket. Example: examplebucket. 
  bucket: 'examplebucket',
});

async function listUploads(query = {}) {
  // You can configure parameters such as prefix, marker, delimiter, upload-id-marker, and max-uploads for query. 
  const result = await client.listUploads(query);

  result.uploads.forEach(upload => {
    console.log(upload.uploadId); // Display the upload IDs of the multipart upload tasks. 
    console.lo g(upload.name); // Display the full path of the object for which the multipart upload task is initiated. 
  });
}

const query = {
  'max-uploads': 1000, // Specify the maximum number of multipart upload tasks to return for the current list operation. The default value and the maximum value of max-uploads are both 1000. 
};
listUploads(query);

List uploaded parts

You can use the client.listParts method to list all parts that are uploaded by using the specified upload ID during the multipart upload task process.

  • List uploaded parts by using simple list

    The following code provides an example on how to list uploaded parts by using simple upload:

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    async function listParts() {
      const query = {
        'max-parts': 1000, // Specify the maximum number of parts to return for the current list operation. The default value and the maximum value of max-parts are both 1000. 
      };
      // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
      const result = await client.listParts('exampledir/exampleobject.txt', '0004B999EF518A1FE585B0C9360D****', query);
    
      result.parts.forEach(part => {
        console.log(part.PartNumber);
        console.log(part.LastModified);
        console.log(part.ETag);
        console.log(part.Size);
      });
    }
    
    listParts();
  • List all uploaded parts

    By default, up to 1,000 parts can be listed at a time by using client.listParts. The following code provides an example on how to list more than 1,000 parts:

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    async function listParts() {
      const query = {
        'max-parts': 1000, // Specify the maximum number of parts to return for the current list operation. The default value and the maximum value of max-parts are both 1000. 
      };
      let result;
      do {
        // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
        result = await client.listParts('exampledir/exampleobject.txt', '0004B999EF518A1FE585B0C9360D****', query);
        // Specify the position from which the list operation starts. Example: 2. Only the parts whose part numbers are greater than the value of this parameter are listed. 
        query['2'] = result.nextPartNumberMarker;
        result.parts.forEach(part => {
          console.log(part.PartNumber);
          console.log(part.LastModified);
          console.log(part.ETag);
          console.log(part.Size);
        });
      } while (result.isTruncated === "true");
    }
    
    listParts();