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
Before you upload an object in parts, familiarize yourself with the multipart upload feature. For more information, see Multipart upload.
When you use bundling tools such as Webpack and Browserify, install OSS SDK for Browser.js by running the npm install ali-oss command.
If you initiate a cross-region access request to an OSS bucket from a browser and no cross-origin resource sharing (CORS) rules are configured for the bucket, the browser rejects the request. To allow cross-origin requests to a bucket from a browser, you must configure CORS rules for the bucket. For more information, see Prerequisites.
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.
Temporary access credentials contain a security token and a temporary AccessKey pair that consists of an AccessKey ID and an AccessKey secret. For more information about how to obtain temporary access credentials, see Use STS for temporary access authorization.
Complete sample code
To upload a large object, you can use multipart upload to upload the object in parts. In multipart upload, an object is split into multiple parts, which are separately uploaded. If some parts fail to be uploaded, you can re-upload only the failed parts based on the upload progress, instead of uploading the whole object again.
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 sample code provides an example on how to use multipart upload to upload the local file exampleobject.txt to the examplebucket bucket.
<!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 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",
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The 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 one or more tags for the object.
"x-oss-tagging": "Tag1=1&Tag2=2",
// Specify whether to overwrite an existing object with the same name when the multipart upload task is initialized. In this example, the x-oss-forbid-overwrite parameter is set to true. This value specifies that an existing object cannot be overwritten by the object that has the same name.
"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";
// Obtain DOM.
const submit = document.getElementById("submit");
const options = {
// Query the progress, checkpoint, and 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 part size. 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",
};
// Configure an event listener.
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 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 content of 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 API operations to perform multipart upload, you must handle the error. To fix the error, you can reduce the part size, 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</button>
<button id="abort">Cancel Upload</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 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",
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The 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",
});
// 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="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 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',
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The 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",
});
// 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");
// Configure an event listener.
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);
}
});
// Configure an event listener.
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 or canceled.
The following sample 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 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 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',
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The 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",
});
// Obtain DOM.
const check = document.getElementById("check");
// Configure an event listener.
check.addEventListener("click", async () => {
// Query multipart upload tasks that have been initiated but are not completed or canceled.
const result = await client.listUploads({ "max-uploads": 100 });
console.log("uploads", result.uploads);
});
</script>
</body>
</html>References
For the complete sample code that is used to perform multipart upload, visit GitHub.
For more information about the API operations that you can call to perform multipart upload, see the following topics:
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 all ongoing multipart upload tasks, see ListMultipartUploads. Ongoing multipart upload tasks include tasks that have been initiated but are not completed or 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
Do not specify the storage class of an object when you call the CompleteMultipartUpload operation. If you want to specify the storage class of an object during multipart upload, you can call the InitiateMultipartUpload operation.