Object Storage Service:Multipart upload using OSS SDK for Node.js

Usage notes

The multipartUpload method splits an object into parts and uploads them individually. If interrupted, only the failed or missing parts are re-uploaded.

If a ConnectionTimeoutError occurs during MultipartUpload, reduce the part size, extend the timeout period, or resend the request. To troubleshoot the root cause, capture the ConnectionTimeoutError error. Network connection timeout handling.

The following parameters are available for multipart upload.

Multipart upload example

The following example uses the multipartUpload method to perform multipart upload:

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

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname',
});


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

const headers = {  
  // Specify the storage class of the object. 
  'x-oss-storage-class': 'Standard', 
  // Specify tags for the object. You can specify multiple tags for the object. 
  'x-oss-tagging': 'Tag1=1&Tag2=2', 
  // Specify whether to overwite an existing object with the same name when the multipart upload task is initialized. In this example, this parameter is set to true, which indicates that an existing object with the same name as the object to upload is not overwritten. 
  'x-oss-forbid-overwrite': 'true'
}

// 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. Do not include the bucket name in the full path. 
    // 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,
      // headers,
      // Configure the meta parameter to specify 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. Do not include the bucket name in the full path. 
    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();

The multipartUpload method wraps the initMultipartUpload, uploadPart, and completeMultipartUpload operations. To perform multipart upload step by step, call these operations directly: .initMultipartUpload, .uploadPart, and .completeMultipartUpload.

Cancel a multipart upload

Call client.abortMultipartUpload to cancel a multipart upload. Canceling an upload invalidates the upload ID and deletes all uploaded parts.

The following example cancels a multipart upload.

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

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: "yourregion",
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: "yourbucketname",
});

async function abortMultipartUpload() {
  // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
  const name = "exampledir/exampleobject.txt";
  // Specify the upload ID. You can obtain the upload ID from the response to the InitiateMultipartUpload operation. 
  const uploadId = "0004B999EF518A1FE585B0C9360D****";
  const result = await client.abortMultipartUpload(name, uploadId);
  console.log(result);
}

abortMultipartUpload();

List ongoing multipart uploads

Call client.listUploads to list all multipart uploads that have been initiated but not completed or canceled.

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

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: "yourregion",
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: "yourbucketname",
});

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

  result.uploads.forEach((upload) => {
    // Specify the upload IDs of the multipart upload tasks. 
    console.log(upload.uploadId);
    // Combine all parts into a complete object and specify the full path of the object. 
    console.log(upload.name);
  });
}

const query = {
  // 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. 
  "max-uploads": 1000,
};
listUploads(query);

List uploaded parts

Call client.listParts to list all parts uploaded for a specific upload ID.

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

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: "yourregion",
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: "yourbucketname",
});

async function listParts() {
  const query = {
    // 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. 
    "max-parts": 1000,
  };
  let result;
  do { 
    result = await client.listParts(
      // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
      "exampledir/exampleobject.txt",
      // Obtain the upload ID from the response to the InitiateMultipartUpload operation. You must obtain the upload ID before you call the CompleteMultipartUpload operation to complete the multipart upload task.
      "0004B999EF518A1FE585B0C9360D****",
      query
    );
    // Specify the starting position of the next list operation. Only parts with part numbers greater than the value of this parameter are listed. 
    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();

References

• Complete multipart upload sample code: GitHub.

• The multipartUpload method wraps these API operations:

  • InitiateMultipartUpload

  • UploadPart

  • CompleteMultipartUpload

• Related API operations:

  • AbortMultipartUpload: Cancels an in-progress multipart upload task and deletes any uploaded parts.

  • ListParts: Lists all successfully uploaded parts for a specific upload task.

  • ListMultipartUploads: Lists all multipart upload tasks that are currently in progress (initiated but not yet completed or aborted).