Multipart upload of objects

Updated at：2025-11-03

Multipart Upload Scenarios

In addition to using the putObject() method for file uploads to BOS, BOS also supports another upload mode called Multipart Upload. This mode can be used in scenarios such as:

When resumable uploads are required.
When uploading files larger than 5GB.
When the connection to the BOS server is frequently interrupted due to unstable network conditions.
Enable streaming file uploads.
The file size cannot be determined before uploading.

Multipart Upload Process

Suppose there is a file with the local path /path/to/file.zip. Since the file is large, multipart upload is used to transmit it to BOS.

Basic workflow:

Start a multipart upload.
Upload individual parts.
Finalize the multipart upload.

Initialize Multipart Upload

Use initiateMultipartUpload method to initialize a multipart upload event:

Example code:

                Java
                
            

                // Initiate Multipart Upload
InitiateMultipartUploadRequest initiateMultipartUploadRequest =
      new InitiateMultipartUploadRequest(<BucketName>, <ObjectKey>);
InitiateMultipartUploadResponse initiateMultipartUploadResponse =
      client.initiateMultipartUpload(initiateMultipartUploadRequest);
 // Print UploadId
System.out.println("UploadId: " + initiateMultipartUploadResponse.getUploadId());
            

Note: The return result of initiateMultipartUpload contains UploadId, which is the unique identifier for distinguishing multipart upload events, and we will use it in subsequent operations.

Upload parts

Upload the file in segments.

Example code:

                Java
                
            

                // Set each part to 5MB
final long partSize = 1024 * 1024 * 5L;
File partFile = new File("/path/to/file.zip");
 // Calculate the count of parts
int partCount = (int) (partFile.length() / partSize);
if (partFile.length() % partSize != 0) {
    partCount++;
}
 // Create a list to save the ETag and PartNumber of each uploaded part
List<PartETag> partETags = new ArrayList<PartETag>();
 // Get file stream
FileInputStream fis = new FileInputStream(partFile);
for (int i = 0; i < partCount; i++) {
 // Calculate the size of each part
    long skipBytes = partSize * i;
    long size = partSize < partFile.length() - skipBytes ?
              partSize : partFile.length() - skipBytes;
    byte[] buf = new byte[(int)size];
    int offset = 0;
    while (true) {
        int byteRead = fis.read(buf, offset, (int)size);
        offset += byteRead;
        if (byteRead < 0 || offset >= size) {
           break;
        }
    }
    ByteArrayInputStream bufStream = new ByteArrayInputStream(buf);
 // Create UploadPartRequest to upload parts
    UploadPartRequest uploadPartRequest = new UploadPartRequest();
    uploadPartRequest.setBucketName(bucketName);
    uploadPartRequest.setKey(objectkey);
    uploadPartRequest.setUploadId(initiateMultipartUploadResponse.getUploadId());
    uploadPartRequest.setInputStream(bufStream);
    uploadPartRequest.setPartSize(size);
    uploadPartRequest.setPartNumber(i + 1);
 // Upload progress callback
    uploadPartRequest.setProgressCallback(new BosProgressCallback<UploadPartRequest>() {
        @Override
        public void onProgress(UploadPartRequest request, long currentSize, long totalSize) {
            Log.e(currentSize + "", totalSize + "");
        }
    });
    UploadPartResponse uploadPartResponse = client.uploadPart(uploadPartRequest);
 // Save the returned PartETag to the List.
    partETags.add(uploadPartResponse.getPartETag());
    System.out.println(uploadPartResponse.getPartETag());
  }
 // Close the file
  fis.close();
            

Note: The core of the above code is to call the UploadPart method to upload each part concurrently, but the following points should be noted:

The UploadPart method requires the size of each part to either be an integer multiple of 1MB or greater than 5MB. However, the Upload Part interface does not validate the part size immediately; this check happens only during the finalization of the multipart upload.

To ensure no errors during network transmission, it is recommended to use the Content-MD5 value returned by BOS for each part after UploadPart to verify the correctness of the uploaded part data. When all part data is combined into one Object, it no longer contains the MD5 value.

The part number must be within the range of 1 to 10,000. If this limit is exceeded, BOS will return an InvalidArgument error code.

For each uploaded part, the stream must be positioned at the beginning of the respective part.

After each Part upload, the return result of BOS will include a PartETag object, which is a combination of the uploaded block's ETag and block number (PartNumber). It will be used in subsequent steps to complete the multipart upload, so it must be saved. Generally speaking, these PartETag objects will be saved in a List.

For details on using the progress callback API, refer to the chapter titled "Obtain Upload Progress."

Complete multipart upload

Example code

                Java
                
            

                CompleteMultipartUploadRequest completeMultipartUploadRequest =
      new CompleteMultipartUploadRequest(<BucketName>, <ObjectKey>,
            initiateMultipartUploadResponse.getUploadId(), partETags);
 // Complete multipart upload
CompleteMultipartUploadResponse completeMultipartUploadResponse =
      client.completeMultipartUpload(completeMultipartUploadRequest);
 // Print Object's ETag
System.out.println(completeMultipartUploadResponse.getETag());
            

Note: The partETags in the above code is the list of partETag saved in the second step. After BOS receives the Part list submitted by the user, it will verify the validity of each data Part one by one. Once all data parts are validated, BOS will assemble the data parts into a complete Object.

Complete example

                Java
                
            

                import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import org.json.JSONException;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.CompleteMultipartUploadRequest;
import com.baidubce.services.bos.model.CompleteMultipartUploadResponse;
import com.baidubce.services.bos.model.InitiateMultipartUploadRequest;
import com.baidubce.services.bos.model.InitiateMultipartUploadResponse;
import com.baidubce.services.bos.model.PartETag;
import com.baidubce.services.bos.model.UploadPartRequest;
import com.baidubce.services.bos.model.UploadPartResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
​    
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
              BosClientConfiguration config = new BosClientConfiguration();
              config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
              config.setEndpoint(<EndPoint>);
              BosClient client = new BosClient(config);
 // Initiate Multipart Upload
              InitiateMultipartUploadRequest initiateMultipartUploadRequest = new InitiateMultipartUploadRequest(<BucketName>, <ObjectKey>);
              InitiateMultipartUploadResponse initiateMultipartUploadResponse =
                        client.initiateMultipartUpload(initiateMultipartUploadRequest);
 // Print UploadId
              System.out.println("UploadId: " + initiateMultipartUploadResponse.getUploadId());
 // Set each part to 5MB
              final long partSize = 1024 * 1024 * 5L;
              File partFile = new File("/path/to/file.zip");
 // Calculate the count of parts
              int partCount = (int) (partFile.length() / partSize);
              if (partFile.length() % partSize != 0) {
                  partCount++;
              }
 // Create a list to save the ETag and PartNumber of each uploaded part
              List<PartETag> partETags = new ArrayList<PartETag>();
 // Get file stream
              FileInputStream fis = new FileInputStream(partFile);
              for (int i = 0; i < partCount; i++) {                       
 // Calculate the size of each part
                  long skipBytes = partSize * i;
                  long size = partSize < partFile.length() - skipBytes ?
                          partSize : partFile.length() - skipBytes;
                  byte[] buf = new byte[(int)size];
                  int offset = 0;
                  while (true) {
                      int byteRead = fis.read(buf, offset, (int)size);
                      offset += byteRead;
                      if (byteRead < 0 || offset >= size) {
                          break;
                      }
                  }
                  ByteArrayInputStream bufStream = new ByteArrayInputStream(buf);
 // Create UploadPartRequest to upload parts
                  UploadPartRequest uploadPartRequest = new UploadPartRequest();
                  uploadPartRequest.setBucketName(<BucketName>);
                  uploadPartRequest.setKey(<ObjectKey>);
                  uploadPartRequest.setUploadId(initiateMultipartUploadResponse.getUploadId());
                  uploadPartRequest.setInputStream(fis);
                  uploadPartRequest.setPartSize(size);
                  uploadPartRequest.setPartNumber(i + 1);
                  UploadPartResponse uploadPartResponse = client.uploadPart(uploadPartRequest);
 // Save the returned PartETag to the List.
                  partETags.add(uploadPartResponse.getPartETag());
                  System.out.println(uploadPartResponse.getPartETag());                                         
              }
 // Close the file
              fis.close();
              CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(<BucketName>, <ObjectKey>, initiateMultipartUploadResponse.getUploadId(), partETags);
 // Complete multipart upload
              CompleteMultipartUploadResponse completeMultipartUploadResponse =
                      client.completeMultipartUpload(completeMultipartUploadRequest);
 // Print Object's ETag
              System.out.println(completeMultipartUploadResponse.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (IOException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            } catch (JSONException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

Cancel multipart upload

Users can cancel multipart uploads by using the abortMultipartUpload method.

Example code:

                Java
                
                AbortMultipartUploadRequest abortMultipartUploadRequest =
    new AbortMultipartUploadRequest(<BucketName>, <ObjectKey>, <UploadId>);
 // Cancel multipart upload
client.abortMultipartUpload(abortMultipartUploadRequest);

Retrieve unfinished multipart uploads

Users can obtain the unfinished multipart upload events in the bucket by the listMultipartUploads method.

Basic workflow

Create an instance of the listMultipartUploadsRequest class, and pass in the parameter <BucketName>.
Create a BOSClient instance and invoke the BOSClient.listMultipartUploads() method.
The listMultipartUploads() method provides details about all uploaded parts.

Example code

                Java
                
            

                ListMultipartUploadsRequest listMultipartUploadsRequest =
    new ListMultipartUploadsRequest(<BucketName>);
 // Retrieve all upload events within the bucket
ListMultipartUploadsResponse list = client.listMultipartUploads(listMultipartUploadsRequest);
​    
 // Traverse all upload events
for (MultipartUploadSummary multipartUpload : list.getMultipartUploads()) {
    System.out.println("Key: " + multipartUpload.getKey() + " UploadId: " + multipartUpload.getUploadId());
}
            

Note:

By default, if the number of multipart upload events in a bucket surpasses 1,000, only 1,000 records will be returned. In such cases, the IsTruncated value in the response will be True, and the NextKeyMarker will indicate the starting point for the next query.

To fetch more multipart upload events, use the KeyMarker parameter to retrieve data in batches.

Complete example

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ListMultipartUploadsRequest;
import com.baidubce.services.bos.model.ListMultipartUploadsResponse;
import com.baidubce.services.bos.model.MultipartUploadSummary;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
                ListMultipartUploadsRequest listMultipartUploadsRequest =
                        new ListMultipartUploadsRequest(<BucketName>);
 // Retrieve all upload events within the bucket
                ListMultipartUploadsResponse listing = client.listMultipartUploads(listMultipartUploadsRequest);
 // Traverse all upload events
                 for (MultipartUploadSummary multipartUpload : listing.getMultipartUploads()) {
                     System.out.println("Key: " + multipartUpload.getKey() + " UploadId: " + multipartUpload.getUploadId());
                 }
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error ErrorType: " + e.getErrorType());
                System.out.println("Error Message: " + e.getMessage());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Get all uploaded part information

Users can obtain all uploaded parts in an upload event by the listParts method.

Basic workflow

Create an instance of the ListPartsRequest class, and pass in the parameters <BucketName>, <ObjectKey> and <UploadId>
Create a BOSClient instance and invoke the BOSClient.listParts() method.
The listParts() method provides details about all uploaded parts.

Example code

                Java
                
            

                ListPartsRequest listPartsRequest = new ListPartsRequest(<BucketName>, <ObjectKey>, <UploadId>);
​    
 // Retrieve all uploaded part information
ListPartsResponse partListing = client.listParts(listPartsRequest);
​    
 // Traverse all parts
for (PartSummary part : partListing.getParts()) {
    System.out.println("PartNumber: " + part.getPartNumber() + " ETag: " + part.getETag());
}
            

Note:

By default, if the number of multipart upload events in a bucket surpasses 1,000, only 1,000 records will be returned. In such cases, the IsTruncated value in the response will be True, and the NextPartNumberMarker will indicate the starting point for the next query.

To retrieve more information about uploaded parts, use the PartNumberMarker parameter to fetch data in batches.

Complete example

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ListPartsRequest;
import com.baidubce.services.bos.model.ListPartsResponse;
import com.baidubce.services.bos.model.PartSummary;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
private String uploadId = <UploadId>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
                ListPartsRequest listPartsRequest = new ListPartsRequest(<BucketName>, <ObjectKey>, <UploadId>);
                listPartsRequest.setMaxParts(100);
                listPartsRequest.setPartNumberMarker(50);
 // Retrieve all uploaded part information
                 ListPartsResponse partListing = client.listParts(listPartsRequest);
 // Traverse all parts
                 for (PartSummary part : partListing.getParts()) {
                     System.out.println("PartNumber: " + part.getPartNumber() + " ETag: " + part.getETag());
                 }
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error ErrorType: " + e.getErrorType());
                System.out.println("Error Message: " + e.getMessage());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Encapsulate multipart upload

In the Android SDK, BOS provides the putSuperObjectFromFile interface, which consolidates the three main methods for multipart uploads: initiateMultipartUpload, UploadPart, and completeMultipartUpload. Using this interface, users can complete a multipart upload with built-in support for progress synchronization callbacks.

Simple example:

                Java
                
                File file = new File("/path/to/file.zip");
PutSuperObjectRequest request = new PutSuperObjectRequest(bucketName, objectKey, file);
bosClient.putSuperObjectFromFile(request);

Example: Set the part size to 2MB, the thread count to 4, and synchronize progress callbacks every 1,024 bytes

                Java
                
            

                BosClientConfiguration config=new BosClientConfiguration();
config.setUploadSegmentPart(1024);
File file = new File("/path/to/file.zip");
PutSuperObjectRequest request = new PutSuperObjectRequest(bucketName, objectKey,
                                                          file, 1024 * 1024 * 2L, 4);
request.setProgressCallback(new BosProgressCallback<PutSuperObjectRequest>() {
    @Override
    public void onProgress(PutSuperObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
bosClient.putSuperObjectFromFile(request);
            

Note:

By default, the part size is 5MB, the thread count is 5, and the progress callback period is every 2,048 bytes.

If a large file takes a long time to upload and the user wants to end the multipart upload, they can call the cancel() method in PutSuperObjectRequest.

Object permission control

Get Object