On this page

Show all

Help Center/ Object Storage Service/ SDK Reference/ BrowserJS/ Object Upload/ Performing a Multipart Upload

Performing a Multipart Upload

Updated on 2024-04-26 GMT+08:00

View PDF

NOTICE:

If you have any questions during development, post them on the Issues page of GitHub. For details about parameters and usage of each API, see the API Reference.

To upload a large file, multipart upload is recommended. Multipart upload is applicable to many scenarios, including:

Files to be uploaded are larger than 100 MB.
The network condition is poor. Connection to the OBS server is constantly down.
Sizes of files to be uploaded are uncertain.

Multipart upload consists of three phases:

Initiate a multipart upload (ObsClient.initiateMultipartUpload).
Upload parts one by one or concurrently (ObsClient.uploadPart).
Combine parts (ObsClient.completeMultipartUpload) or abort the multipart upload (ObsClient.abortMultipartUpload).

NOTE:

You can also call the API for resumable upload (encapsulation and enhancement of multipart upload) provided by the SDK to implement multipart upload.

Initiating a Multipart Upload

Before using a multipart upload, you need to first initiate it. This operation will return an upload ID (globally unique identifier) created by the OBS server to identify the multipart upload. You can use this upload ID to initiate related operations, such as aborting a multipart upload, listing multipart uploads, and listing uploaded parts.

You can call ObsClient.initiateMultipartUpload to initiate a multipart upload.

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

obsClient.initiateMultipartUpload({
       Bucket : 'bucketname',
       Key : 'objectname',
       ContentType : 'text/plain',
       Metadata : {'property' : 'property-value'}
}, function (err, result) {
       if(err){
              console.error('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                     console.log('UploadId-->' + result.InterfaceResult.UploadId);
              }
       }
});

NOTE:

When initiating a multipart upload, you can use the ContentType and Metadata parameters to respectively set the MIME type and custom metadata of an object.
After the API for initiating a multipart upload is successfully called, an upload ID will be returned. This ID will be used in follow-up operations.

Uploading a Part

After initiating a multipart upload, you can specify the object name and upload ID to upload a part. Each upload part has a part number (ranging from 1 to 10000). For parts with the same upload ID, their part numbers are unique and identify their relative location in the object. If you use the same part number to upload two parts, the latter one uploaded will overwrite the former one. The last part uploaded can be up to 5 GB in size, and the size of each of the other parts is in the range of 100 KB to 5 GB. Parts can be uploaded in random order, or even through different processes or machines. OBS will combine them into the final object based on their part numbers.

You can call ObsClient.uploadPart to upload parts.

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

const bucketname = 'examplebucket';
const objectname = 'exampleobject';
const PartSize = 5 * 1024 * 1024;
const Uploadid = 'upload id from initiateMultipartUpload';
const file = document.getElementById('input-file').files[0];
const lastPartSize = file.size % PartSize;
// Number of parts
const count = Math.ceil(file.size / PartSize);
// Upload part n.
const uploadPart = (n) => {
    obsClient.uploadPart({
        Bucket: bucketname,
        Key: objectname,
       // Set the part number, which ranges from 1 to 10000.
        PartNumber: n,
       // Set the upload ID.
        UploadId,
       // Specify the large file to be uploaded.
        SourceFile: file,
       // Set the part size.
        PartSize: count === n ? lastPartSize : PartSize,
       // Set the start offset.
        Offset: (n-1) * PartSize
    }, function (err, result) {
        if(err){
                console.log('Error-->' + err);
        }else{
                console.log('Status-->' + result.CommonMsg.Status);
                if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                      console.log('ETag-->' + result.InterfaceResult.ETag);
                }
        }
    });
}

// Upload part 1.
uploadPart(1);

CAUTION:

If the ETag value obtained is undefined, you need to configure a CORS rule and add the ETag to the additional header. For details, see ETag.

NOTE:

Use the PartNumber parameter to specify the part number, the UploadId parameter to specify the globally unique ID, the SourceFile parameter to specify the to-be-uploaded file, the PartSize parameter to set the part size, and the Offset parameter to set the start offset of the file.
SourceFile must indicate a File or Blob object. For example, on an HTML page, use an input tag whose type is file to specify the to-be-uploaded file: <input type="file" id="input-file"/>.
Except the part last uploaded, other parts must be larger than 100 KB. Part sizes will not be verified during upload because which one is last uploaded is not identified until parts are combined.
OBS will return ETags (MD5 values) of the received parts to users.
You can use the ContentMD5 parameter to set the MD5 value of the uploaded data.
Part numbers range from 1 to 10000. If the part number you set is out of this range, OBS will return error 400 Bad Request.
The minimum part size supported by an OBS 3.0 bucket is 100 KB, and the minimum part size supported by an OBS 2.0 bucket is 5 MB. You are advised to perform multipart upload to OBS 3.0 buckets.

Combining Parts

After all parts are uploaded, call the API for combining parts to generate the object. Before this operation, valid part numbers and ETags of all parts must be sent to OBS. After receiving this information, OBS verifies the validity of each part one by one. After all parts pass the verification, OBS combines these parts to form the final object.

You can call ObsClient.completeMultipartUpload to combine parts.

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

obsClient.completeMultipartUpload({
       Bucket:'bucketname',
       Key:'objectname',
       // Set the upload ID.
       UploadId:'upload id from initiateMultipartUpload',
       Parts: [{'PartNumber':1,'ETag':'etag value from uploadPart'}]
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
       }
});

CAUTION:

If the size of a part other than the last part is smaller than 100 KB, OBS returns 400 Bad Request.

NOTE:

Use the UploadId parameter to specify the globally unique identifier for the multipart upload and the Parts parameter to specify the list of part numbers and ETags. Content in the list is displayed in the ascending order by part number.
Part numbers can be inconsecutive.

Aborting a Multipart Upload

After a multipart upload is aborted, you cannot use its upload ID to perform any operation and the uploaded parts will be deleted by OBS.

When an object is being uploaded in multi-part mode or an object fails to be uploaded, parts are generated in the bucket. These parts occupy your storage space. You can cancel the multi-part uploading task to delete unnecessary parts, thereby saving the storage space.

You can call ObsClient.abortMultipartUpload to abort a multipart upload.

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

obsClient.abortMultipartUpload({
       Bucket:'bucketname',
       Key:'objectname',
       // Set the upload ID.
       UploadId:'upload id from initiateMultipartUpload',
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
       }
});

Listing Uploaded Parts

You can call ObsClient.listParts to list successfully uploaded parts of a multipart upload.

The following table describes the parameters involved in this API.

Parameter	Description
UploadId	Upload ID, which globally identifies a multipart upload. The value is in the returned result of ObsClient.initiateMultipartUpload.
MaxParts	Maximum number of parts that can be listed per page.
PartNumberMarker	Part number after which listing uploaded parts begins. Only parts whose part numbers are larger than this value will be listed.

Listing parts in simple mode

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

// List uploaded parts. uploadId is obtained from initiateMultipartUpload.
obsClient.listParts({
       Bucket : 'bucketname',
       Key: 'objectname',
       UploadId : 'upload id from initiateMultipartUpload'
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                     for(var i in result.InterfaceResult.Parts){
                           console.log('Part['+ i +']:');
                           // Part number, specified upon uploading
                           console.log('PartNumber-->' + result.InterfaceResult.Parts[i]['PartNumber']);
                           // Time when the part was last uploaded
                           console.log('LastModified-->' + result.InterfaceResult.Parts[i]['LastModified']);
                           // Part ETag
                           console.log('ETag-->' + result.InterfaceResult.Parts[i]['ETag']);
                           // Part size
                           console.log('Size-->' + result.InterfaceResult.Parts[i]['Size']);
                     }
              }
       }
});

NOTE:

A maximum of 1,000 parts can be listed each time. If the upload of a specified ID contains more than 1,000 parts, InterfaceResult.IsTruncated in the response is true, indicating not all parts were listed. In such case, you can use InterfaceResult.NextPartNumberMarker to obtain the start position for the next listing.
If you want to obtain all parts involved in a specific upload ID, you can use the paging mode for listing.

Listing all parts

The following sample code lists more than 1,000 parts:

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

var listAll = function (partNumberMarker) {
       // List uploaded parts. uploadId is obtained from initiateMultipartUpload.
       obsClient.listParts({
              Bucket : 'bucketname',
              Key: 'objectname',
              UploadId : 'upload id from initiateMultipartUpload',
              PartNumberMarker : partNumberMarker
       }, function (err, result) {
              if(err){
                     console.log('Error-->' + err);
              }else{
                     console.log('Status-->' + result.CommonMsg.Status);
                     if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                           for(var i in result.InterfaceResult.Parts){
                                  console.log('Part['+ i +']:');
                           // Part number, specified upon uploading
                                  console.log('PartNumber-->' + result.InterfaceResult.Parts[i]['PartNumber']);
                           // Time when the part was last uploaded
                                  console.log('LastModified-->' + result.InterfaceResult.Parts[i]['LastModified']);
                           // Part ETag
                                  console.log('ETag-->' + result.InterfaceResult.Parts[i]['ETag']);
                                  // Part size
                                  console.log('Size-->' + result.InterfaceResult.Parts[i]['Size']);
                           }
                           if(result.InterfaceResult.IsTruncated === 'true'){
                                  listAll(result.InterfaceResult.NextPartNumberMarker);
                           }
                     }
              }
       });
};

listAll();

Listing Multipart Uploads

You can call ObsClient.listMultipartUploads to list multipart uploads. The following table describes parameters involved in ObsClient.listMultipartUploads.

Parameter	Description
Prefix	Prefix that the object names in the multipart uploads to be listed must contain
Delimiter	Character used to group object names involved in multipart uploads. If the object name contains the Delimiter parameter, the character string from the first character to the first delimiter in the object name is grouped under a single result element, CommonPrefix. (If a prefix is specified in the request, the prefix must be removed from the object name.)
MaxUploads	Maximum number of multipart uploads listed in the response body. The value ranges from 1 to 1000. If the value exceeds 1000, only 1,000 multipart uploads are returned.
KeyMarker	Object name to start with when listing multipart uploads
UploadIdMarker	Upload ID after which the multipart upload listing begins. It is effective only when used with KeyMarker so that multipart uploads after UploadIdMarker of KeyMarker will be listed.

Listing multipart uploads in simple mode

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

obsClient.listMultipartUploads({
       Bucket : 'bucketname'
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                     for(var i in result.InterfaceResult.Uploads){
                           console.log('Uploads[' + i + ']');
                           console.log('UploadId-->' + result.InterfaceResult.Uploads[i]['UploadId']);
                           console.log('Key-->' + result.InterfaceResult.Uploads[i]['Key']);
                           console.log('Initiated-->' + result.InterfaceResult.Uploads[i]['Initiated']);
                     }
              }
       }
});

NOTE:

A maximum of 1,000 multipart uploads can be listed each time. If a bucket contains more than 1,000 multipart uploads, InterfaceResult.IsTruncated in the response is true, indicating not all uploads were listed. In such case, you can use InterfaceResult.NextKeyMarker and InterfaceResult.NextUploadIdMarker to obtain the start position for the next listing.
If you want to obtain all multipart uploads in a bucket, you can list them in paging mode.

Listing all multipart uploads

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

var listAll = function (keyMarker, uploadIdMarker) {
       obsClient.listMultipartUploads({
              Bucket : 'bucketname',
              KeyMarker : keyMarker,
              UploadIdMarker : uploadIdMarker
       }, function (err, result) {
              if(err){
                     console.log('Error-->' + err);
              }else{
                     console.log('Status-->' + result.CommonMsg.Status);
                     if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                           for(var i in result.InterfaceResult.Uploads){
                                  console.log('Uploads[' + i + ']');
                                  console.log('UploadId-->' + result.InterfaceResult.Uploads[i]['UploadId']);
                                  console.log('Key-->' + result.InterfaceResult.Uploads[i]['Key']);
                                  console.log('Initiated-->' + result.InterfaceResult.Uploads[i]['Initiated']);
                           }
                           
                           if(result.InterfaceResult.IsTruncated === 'true'){
                                  listAll(result.InterfaceResult.NextKeyMarker, result.InterfaceResult.NextUploadIdMarker);
                           }
                     }
              }
       });
}

listAll();

Parent topic: Object Upload

Previous topic: Setting Object Properties

Next topic: Configuring Lifecycle Management

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot