This topic describes how to upload an object by using 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 table describes parameters that you can set in multipart upload.

Type Parameter Description
Required parameters name {String} The name of the object.
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 multipart upload. 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 file, the file is deleted.
[parallel] {Number} The number of parts that can be uploaded concurrently. Default value: 5. Do not modify the value of this parameter unless necessary.
[partSize] {Number} The size of each part to upload. Valid value: 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. It can be an async function. The callback function involves the following three parameters:
  • percentage {Number}: the upload progress in percentage. Valid value: decimals from 0 to 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} User-defined header metadata, which is prefixed by x-oss-meta.
[mime] {String} The Content-Type request header.
[headers] {Object} Other headers. For more information, visit RFC 2616. Some headers are described as follows:
  • Cache-Control: Used in HTTP requests or responses to configure caching behaviors by using specified commands. Example:Cache-Control: public, no-cache.
  • Content-Disposition: Specifies whether the returned content is displayed in a web page or downloaded as an attachment. Example: Content-Disposition: somename.
  • Content-Encoding: Compresses data of the specified media type. Example: Content-Encoding: gzip.
  • Expires: Specifies the validity period of the request. Unit: millisecond. Example: Expires: 3600000.

The following code provides an example on how to upload an object by using multipart upload: 

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>',
});

// Start multipart upload.
async function multipartUpload () {
  try {
    // Set object-name 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-name', 'file-object', {
    progress,
    // meta specifies the user metadata. You can obtain the object metadata by using the head operation.
    meta: {
      year: 2020,
      people: 'test'
    }
  });
  console.log(result);
  let 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)
  }
}