Multipart upload splits a large file into parts that upload independently to OSS. After all parts are uploaded, OSS combines them into a single object. Use multipart upload for files larger than 100 MB — it supports resumable uploads and retries, so a network interruption requires re-uploading only the failed parts, not the entire file. For files smaller than 100 MB, use simple upload instead.
Prerequisites
Before you begin, ensure that you have:
Reviewed the multipart upload concepts
Configured cross-origin resource sharing (CORS) rules for your bucket — without CORS, the browser blocks all OSS requests. For setup steps, see Preparations
Obtained temporary access credentials (a temporary AccessKey pair and security token) from Security Token Service (STS) — the Browser.js SDK runs in the browser, so never use your permanent AccessKey pair. See Grant access (Browser.js SDK)
(Optional) Installed the SDK via npm if you use a bundler:
npm install ali-oss
How it works
The multipartUpload method encapsulates three API operations that run in sequence:
InitiateMultipartUpload— starts the upload session and returns anuploadIdUploadPart— uploads each part concurrently up to the configuredparallellimitCompleteMultipartUpload— assembles all parts into the final object
The progress callback fires after each part completes and receives three arguments:
| Argument | Description |
|---|---|
p | Upload ratio from 0 to 1. Use this to render a progress bar. |
cpt | Checkpoint object containing the name, uploadId, and part state. Needed for abort and list operations. |
res | The raw HTTP response for the last completed part. |
Upload a file
The following example uploads a file selected from an <input> element to examplebucket.
Use multipart upload only for files larger than 100 MB. Setting an improper partSize for smaller files can cause the progress indicator to display incorrectly.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<input id="file" type="file" />
<!--Import the SDK file.-->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
const client = new OSS({
// Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
region: "yourRegion",
authorizationV4: true,
// The temporary AccessKey ID and AccessKey secret obtained from STS.
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// The security token obtained from STS.
stsToken: "yourSecurityToken",
// Specify the bucket name, for 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 it is downloaded.
"Content-Disposition": "example.txt",
// Specify the expiration time in 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.
"x-oss-tagging": "Tag1=1&Tag2=2",
// Specify whether to overwrite an object that has the same name when you initialize a multipart upload. A value of true indicates that overwriting is prohibited.
"x-oss-forbid-overwrite": "true",
};
// Specify the name of the object to be uploaded to examplebucket, for example, exampleobject.txt.
const name = "exampleobject.txt";
const submit = document.getElementById("submit");
const options = {
// p: upload ratio (0-1). cpt: checkpoint with name and uploadId. res: last HTTP response.
progress: (p, cpt, res) => {
console.log(p);
},
// Number of parts to upload concurrently.
parallel: 4,
// Part size in bytes. Default: 1 MB (1024 * 1024). Minimum: 100 KB. Maximum: 5 GB. The last part may be smaller than 100 KB.
partSize: 1024 * 1024,
// headers,
// Custom metadata. Retrieve it later by calling the HeadObject operation.
meta: { year: 2020, people: "test" },
mime: "text/plain",
};
submit.addEventListener("click", async () => {
try {
const data = document.getElementById("file").files[0];
const res = await client.multipartUpload(name, data, {
...options,
// Upload callback. Remove this block if you do not have a callback server.
callback: {
// Address of the callback server.
url: "http://examplebucket.aliyuncs.com:23450",
// Host header value in the callback request.
host: "yourHost",
/* eslint no-template-curly-in-string: [0] */
// Request body sent in the callback.
body: "bucket=${bucket}&object=${object}&var1=${x:var1}",
// Content-Type of the callback request.
contentType: "application/x-www-form-urlencoded",
customValue: {
// Custom parameters for the callback.
var1: "value1",
var2: "value2",
},
},
});
console.log(res);
} catch (err) {
console.log(err);
}
});
</script>
</body>
</html>If a ConnectionTimeoutError occurs, reduce the partSize, increase the timeout period, or retry the request. For more information, see Handle network errors.
Cancel an upload
Call client.abortMultipartUpload to cancel an in-progress upload. After cancellation, the uploadId is invalidated and all uploaded parts for that session are deleted from OSS.
The following example adds an Abort button. Clicking it cancels the upload and cleans up any parts already uploaded.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<button id="abort">Abort</button>
<!--Import the SDK file.-->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
const client = new OSS({
// Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
region: "yourRegion",
authorizationV4: true,
// The temporary AccessKey ID and AccessKey secret obtained from STS.
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// The security token obtained from STS.
stsToken: "yourSecurityToken",
// Specify the bucket name, for example, examplebucket.
bucket: "examplebucket",
});
// Generate a 100 MB file for multipart upload.
const fileContent = Array(1024 * 1024 * 100)
.fill("a")
.join("");
const file = new File([fileContent], "multipart-upload-file");
// Object name in examplebucket, for example, exampleobject.txt.
const name = "exampleobject.txt";
// Stores the checkpoint from the progress callback, used to abort the upload.
let abortCheckpoint;
const submit = document.getElementById("submit");
const abort = document.getElementById("abort");
submit.addEventListener("click", async () => {
try {
const res = await client.multipartUpload(name, file, {
progress: (p, cpt, res) => {
// Save the checkpoint so it can be passed to abortMultipartUpload.
abortCheckpoint = cpt;
console.log(p);
},
});
} catch (err) {
console.log(err);
}
});
abort.addEventListener("click", () => {
client.abortMultipartUpload(
abortCheckpoint.name,
abortCheckpoint.uploadId
);
});
</script>
</body>
</html>List uploaded parts
Call client.listParts to retrieve all successfully uploaded parts for a given uploadId. This is useful for inspecting upload state before deciding whether to resume or abort.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<button id="check">List uploaded parts</button>
<!--Import the SDK file.-->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
const client = new OSS({
// Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
region: "yourRegion",
authorizationV4: true,
// The temporary AccessKey ID and AccessKey secret obtained from STS.
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// The security token obtained from STS.
stsToken: "yourSecurityToken",
// Specify the bucket name, for example, examplebucket.
bucket: "examplebucket",
});
// Generate a 100 MB file for multipart upload.
const fileContent = Array(1024 * 1024 * 100)
.fill("a")
.join("");
const file = new File([fileContent], "multipart-upload-file");
// Object name in examplebucket, for example, exampleobject.txt.
const name = "exampleobject.txt";
// Stores the checkpoint from the progress callback, used to list parts.
let abortCheckpoint;
const submit = document.getElementById("submit");
const check = document.getElementById("check");
submit.addEventListener("click", async () => {
try {
const res = await client.multipartUpload(name, file, {
progress: (p, cpt, res) => {
abortCheckpoint = cpt;
console.log(p);
},
});
} catch (err) {
console.log(err);
}
});
check.addEventListener("click", async () => {
const result = await client.listParts(name, abortCheckpoint.uploadId);
console.log(result);
});
</script>
</body>
</html>List multipart upload events
Call client.listUploads to retrieve all in-progress multipart upload events — events that have been initiated but not yet completed or canceled.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="check">List multipart upload events</button>
<!--Import the SDK file.-->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
const client = new OSS({
// Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
region: "yourRegion",
authorizationV4: true,
// The temporary AccessKey ID and AccessKey secret obtained from STS.
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// The security token obtained from STS.
stsToken: "yourSecurityToken",
// Specify the bucket name, for example, examplebucket.
bucket: "examplebucket",
});
const check = document.getElementById("check");
check.addEventListener("click", async () => {
const result = await client.listUploads({ "max-uploads": 100 });
console.log("uploads", result.uploads);
});
</script>
</body>
</html>FAQ
Why do I get "PLease set the etag of expose-headers in Oss."?
Your CORS rules are missing required exposed headers. Open your bucket's CORS settings and add x-oss-request-id and ETag to the exposed headers list. For the full configuration steps, see Configure CORS.
Why do I get "The operation is not supported for this resource."?
This error occurs when you try to set the storage class during CompleteMultipartUpload. Set the storage class during InitiateMultipartUpload instead — use the x-oss-storage-class header in the headers option when calling multipartUpload.
What's next
Complete sample code on GitHub: multipartUpload example
API reference for the operations that
multipartUploadencapsulates: