Object Storage Service (OSS) provides the multipart upload feature. Multipart upload allows you to split a large object into multiple parts to upload. After the parts are uploaded, you can call the CompleteMultipartUpload operation to combine the parts into a complete object. This way, you can upload an object in a resumable manner.

Usage notes

  • When you use packaging tools such as Webpack and Browserify, install OSS SDK for Browser.js by running the npm install ali-oss command.
  • In most cases, OSS SDK for Browser.js is used in browsers. To prevent your AccessKey pair from being exposed, we recommend that you use temporary access credentials obtained from Security Token Service (STS) to access OSS.

    For more information about how to use STS, see Use temporary credentials provided by STS to access OSS in OSS Developer Guide. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain temporary access credentials. Temporary access credentials include a security token and a temporary AccessKey pair that consists of an AccessKey ID and an AccessKey secret.

Complete sample code

To upload a large object, you can call the MultipartUpload operation to perform multipart upload. In multipart upload, an object is split into multiple parts. Then, the parts are separately uploaded. If some parts fail to be uploaded, you can reupload only these parts based on the upload progress.

Important To upload an object whose size is larger than 100 MB, we recommend that you use multipart upload to increase the success rate of the upload. If multipart upload is used to upload an object whose size is smaller than 100 MB and the value of the partSize parameter is inappropriate, the upload progress may not be fully displayed. To upload an object whose size is smaller than 100 MB, we recommend that you use simple upload.

The following code provides an example on how to use multipart upload to upload a local file to the examplebucket bucket. The uploaded object is named exampleobject.txt. 

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>

  <body>
    <button id="submit">Upload an Object</button>
    <input id="file" type="file" />
    <!-- import an SDK file -->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.16.0.min.js"
    ></script>
    <script type="text/javascript">
      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",
        // Specify the temporary AccessKey pair obtained from Security Token Service (STS). An AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
        accessKeyId: "yourAccessKeyId",
        accessKeySecret: "yourAccessKeySecret",
        // Specify the security token obtained from STS. 
        stsToken: "yourSecurityToken",
        // Specify the name of the bucket. Example: examplebucket. 
        bucket: "examplebucket",
      });

      const headers = {
        // Specify the caching behavior of the web page when the object is downloaded. 
        "Cache-Control": "no-cache",
        // Specify the name of the object when the object is downloaded. 
        "Content-Disposition": "example.txt",
        // Specify the content encoding format of the object when the object is downloaded. 
        "Content-Encoding": "utf-8",
        // Specify the validity period of the request. Unit: milliseconds. 
        "Expires": "1000",
        // Specify the storage class of the object. 
        "x-oss-storage-class": "Standard",
        // Specify tags for the object. You can specify multiple tags at the same time. 
        "x-oss-tagging": "Tag1=1&Tag2=2",
        // Specify whether the object that is uploaded by using multipart upload overwrites the existing object that has the same name when the multipart upload task is initiated. In this example, the x-oss-forbid-overwrite parameter is set to true, which specifies that existing objects cannot be overwritten by objects that have the same names. 
        "x-oss-forbid-overwrite": "true",
      };

      // Specify the name of the object that is uploaded to the examplebucket bucket. Example: exampleobject.txt. 
      const name = "exampleobject.txt";
      // Query DOM. 
      const submit = document.getElementById("submit");
      const options = {
        // Query the progress, the checkpoint, and the return value of the multipart upload task. 
        progress: (p, cpt, res) => {
          console.log(p);
        },
        // Specify the number of parts that can be uploaded in parallel. 
        parallel: 4,
        // Specify the size of each part. Default value: 1 MB. Minimum value: 100 KB. 
        partSize: 1024 * 1024,
        // headers,
        // Specify the user metadata of the object. You can call the HeadObject operation to query the object metadata. 
        meta: { year: 2020, people: "test" },
        mime: "text/plain",
      };

      // Create a button that is used to start the multipart upload task. 
      submit.addEventListener("click", async () => {
        try {
          const data = document.getElementById("file").files[0];
          // Start the multipart upload task. 
          const res = await client.multipartUpload(name, data, {
            ...options,
            // Configure an upload callback. 
            // If no callback server is required, delete the callback configurations. 
            callback: {
              // Specify the address of the callback server that receives the callback request. 
              url: "http://examplebucket.aliyuncs.com:23450",
              // Specify the Host header in the callback request. 
              host: "yourHost",
              /* eslint no-template-curly-in-string: [0] */
              // Specify the body field included in the callback request. 
              body: "bucket=${bucket}&object=${object}&var1=${x:var1}",
              // Specify Content-Type in the callback request. 
              contentType: "application/x-www-form-urlencoded",
              customValue: {
                // Specify custom parameters for the callback request. 
                var1: "value1",
                var2: "value2",
              },
            },
          });
          console.log(res)
        } catch (err) {
          console.log(err);
        }
      });
    </script>
  </body>
</html>

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

Cancel a multipart upload task

You can use the client.abortMultipartUpload method 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:

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>Document</title>
</head>

<body>
  <button id='submit'>Upload an Object</button>
  <button id='abort'>Cancel Upload</button>
     <!-- import an SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.16.0.min.js"></script>
  <script type="text/javascript">
    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',
       // Specify the temporary AccessKey pair obtained from STS. 
       accessKeyId: 'yourAccessKeyId',
       accessKeySecret: 'yourAccessKeySecret',
       // Specify the security token obtained from STS. 
       stsToken: 'yourSecurityToken',
       // Specify the name of the bucket. Example: examplebucket. 
       bucket: "examplebucket",
      });
    // Create a local file that you want to upload to the bucket by using multipart upload. The size of the file is 100 MB.   
    const fileContent = Array(1024 * 1024 * 100).fill('a').join('')
    const file = new File([fileContent], 'multipart-upload-file')
    // Specify the name of the object that is uploaded to the examplebucket bucket. Example: exampleobject.txt. 
    const name = "exampleobject.txt";
    // Specify the checkpoint at which the multipart upload task is canceled. 
    let abortCheckpoint
    // Query DOM. 
    const submit = document.getElementById('submit');
    const abort = document.getElementById('abort')

    // Create a button that is used to start the multipart upload task. 
    submit.addEventListener('click', async () => {
      try {
        const res = await client.multipartUpload(name, file, {
          progress: (p, cpt, res) => {
            // Assign a value to the checkpoint. 
            abortCheckpoint = cpt
            // Query the progress of the multipart upload task. 
            console.log(p)
          }
        })
      } catch (err) {
        console.log(err)
      }
    })
    // Create a button that is used to cancel the multipart upload task. 
    abort.addEventListener('click', () => {
    // Cancel the multipart upload task. 
    client.abortMultipartUpload(abortCheckpoint.name, abortCheckpoint.uploadId)
    })
  </script>
</body>

</html>

List uploaded parts

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

The following code provides an example on how to list uploaded parts:

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>Document</title>
</head>

<body>
  <button id='check'>List Uploaded Parts</button>
  <!-- import an SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.16.0.min.js"></script>
  <script type="text/javascript">
    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',
       // Specify the temporary AccessKey pair obtained from STS. 
       accessKeyId: 'yourAccessKeyId',
       accessKeySecret: 'yourAccessKeySecret',
       // Specify the security token obtained from STS. 
       stsToken: 'yourSecurityToken',
       // Specify the name of the bucket. Example: examplebucket. 
       bucket: "examplebucket",
      });
    // Create a local file that you want to upload to the bucket by using multipart upload. The size of the file is 100 MB.     
    const fileContent = Array(1024 * 1024 * 100).fill('a').join('')
    const file = new File([fileContent], 'multipart-upload-file')
    // Specify the name of the object that is uploaded to the examplebucket bucket. Example: exampleobject.txt. 
    const name = "exampleobject.txt";
    // Specify the checkpoint at which the multipart upload task is canceled. 
    let abortCheckpoint

    // Query DOM. 
    const submit = document.getElementById('submit');
    const check = document.getElementById('check')

    // Create a button that is used to start the multipart upload task. 
    submit.addEventListener('click', async () => {
      try {
        const res = await client.multipartUpload(name, file, {
          progress: (p, cpt, res) => {
            // Assign a value to the checkpoint. 
            abortCheckpoint = cpt
            // Query the progress of the multipart upload task. 
            console.log('progress=====', p)
          }
        })
      } catch (err) {
        console.log(err)
      }
    })
      // Create a button that is used to start the multipart upload task. 
      check.addEventListener('click', async () => {
      // List the uploaded parts.
      const result = await client.listParts(name, abortCheckpoint.uploadId)
      console.log(result)
    })
  </script>
</body>

</html>

List multipart upload tasks

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

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

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>Document</title>
</head>

<body>
  <button id='check'>List Multipart Upload Tasks</button>
  <!-- import an SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.16.0.min.js"></script>
  <script type="text/javascript">
      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',
         // Specify the temporary AccessKey pair obtained from STS. 
         accessKeyId: 'yourAccessKeyId',
         accessKeySecret: 'yourAccessKeySecret',
         // Specify the security token obtained from STS. 
        stsToken: 'yourSecurityToken',
        // Specify the name of the bucket. Example: examplebucket. 
        bucket: "examplebucket",
    });

    // Query DOM. 
    const check = document.getElementById('check')

    // Create a button that is used to start the multipart upload task. 
    check.addEventListener('click', async () => {
      // Query multipart upload tasks that have been initiated but are not completed or are canceled. 
      const result = await client.listUploads({ 'max-uploads': 100 })
      console.log('uploads', result.uploads)
    })
  </script>
</body>

</html>

References

  • For more information about the complete sample code of multipart upload, visit GitHub.
  • The multipartUpload method that is used by OSS SDK for Browser.js to perform multipart upload contains the following three API operations:
    • The API operation that you can call to initiate a multipart upload task. For more information, see InitiateMultipartUpload.
    • The API operation that you can call to upload data by part. For more information, see UploadPart.
    • The API operation that you can call to complete a multipart upload task. For more information, see CompleteMultipartUpload.
  • For more information about the API operation that you can call to cancel a multipart upload task, see AbortMultipartUpload.
  • For more information about the API operation that you can call to list uploaded parts, see ListParts.
  • For more information about the API operation that you can call to list ongoing multipart upload tasks, see ListMultipartUploads. Ongoing multipart upload tasks include tasks that have been initiated but are not completed or are canceled.

FAQ

What do I do if the PLease set the etag of expose-headers in Oss. error message is returned?

  • Cause

    The cross-origin resource sharing (CORS) rules are incorrectly configured.

  • Solution

    You must configure a CORS rule for the current bucket. Specify common headers, such as x-oss-request-id and ETag, when you configure the CORS rule. For more information, see CORS.

What do I do if the The operation is not supported for this resource. error message is returned?

  • Cause

    You specified the storage class of the object when you call the CompleteMultipartUpload operation.

  • Solution

    You cannot specify the storage class of an object when you call the CompleteMultipartUpload operation during multipart upload. If you want to specify the storage class of an object during multipart upload, you can call the InitiateMultipartUpload operation.