Multipart upload

Background information

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 table describes parameters that you can configure for multipart upload.

Complete sample code

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

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

const client = new OSS({
  // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
  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 a RAM user, log on to the RAM console.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: '<Your bucket name>',
});

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 {
    // Set object-name to a name such as file.txt or a folder such as abc/test/file.txt to upload the object to the current bucket or the specified folder in the bucket.
    const result = await client.multipartUpload('<Object Name>', 'file-object', {
      progress,
      // meta specifies the user metadata. You can query the object metadata by calling the HeadObject operation.
      meta: {
        year: 2020,
        people: 'test',
      },
    });
    console.log(result);
    const head = await client.head('object-name');
    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 a multipart upload task is canceled, the upload ID can no longer be used to upload any parts. The parts uploaded by using the upload ID are also deleted.

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

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

const client = new OSS({
  // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
  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 a RAM user, log on to the RAM console.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: '<Your bucket name>',
});

async function abortMultipartUpload() {
  const name = '<Object Name>'; // The full path of the object in a bucket.
  const uploadId = '<Upload Id>'; // The upload ID of the multipart upload task.
  const result = await client.abortMultipartUpload(name, uploadId);
  console.log(result);
}

abortMultipartUpload();

List multipart upload tasks

The following sample code provides an example on how to call listUploads to list multipart upload tasks:

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

const client = new OSS({
  // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
  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 a RAM user, log on to the RAM console.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: '<Your bucket name>',
});

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); // The upload ID of the multipart upload task.
    console.lo g(upload.name); // Combine all uploaded parts into a complete object and specify the full path of the object in a bucket.
  });
}

const query = {
  'max-uploads': 1000, // Specify the maximum number of multipart upload tasks to return at a time. The default value is 1000. The maximum value is 1000.
};
listUploads(query);

List uploaded parts

You can call ossClient.listParts to list all parts that are uploaded by using the specified upload ID.

• Simple list

  The following code provides an example of simple list:

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
    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 a RAM user, log on to the RAM console.
    accessKeyId: '<Your AccessKeyId>',
    accessKeySecret: '<Your AccessKeySecret>',
    bucket: '<Your bucket name>',
  });
  
  async function listParts() {
    const query = {
      'max-parts': 1000, // Specify the maximum number of parts that can be returned in the OSS response. The default value is 1000. The maximum value is 1000.
    };
    const result = await client.listParts('<Object Name>', '<Upload Id>', 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, listParts can list up to 1,000 parts at a time. The following code provides an example on how to list more than 1,000 parts:

  const OSS = require('ali-oss')
  
  const client = new OSS({
    // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
    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 a RAM user, log on to the RAM console.
    accessKeyId: '<Your AccessKeyId>',
    accessKeySecret: '<Your AccessKeySecret>',
    bucket: '<Your bucket name>',
  });
  
  async function listParts() {
    const query = {
      'max-parts': 1000, // Specify the maximum number of parts that can be returned in the OSS response. The default value is 1000. The maximum value is 1000.
    };
    let result;
    do {
      result = await client.listParts('<Object Name>', '<Upload Id>', query);
      // Set the position from which the list begins.
      query['part-number-marker'] = 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();