This topic describes how to use multipart upload.

For more information about multipart upload, see Multipart upload. For the complete code used to perform multipart upload, see GitHub.

To perform multipart upload, follow these steps:

  1. Initiate a multipart upload task.

    Use the ossClient.initiateMultipartUpload method to obtain an upload ID that is globally unique in OSS.

  2. Start multipart upload.

    Use the ossClient.uploadPart method to upload the parts.

    Note
    • For parts that share an upload ID, partNumber identifies the relative position of a part in the entire object. If you have uploaded a part and used its partNumber again to upload another part, the latter part overwrites the former part.
    • OSS places the MD5 value of part data in the ETag header and returns the MD5 value to the user.
    • OSS calculates the MD5 value of uploaded data and compares it with the MD5 value calculated by the SDK. If the two values are different, the InvalidDigest error code is returned.
  3. Complete multipart upload.

    After all of the parts have been uploaded, use the ossClient.completeMultipartUpload method to combine these parts into a complete object.

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

// This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";
// <yourObjectName> indicates the complete path of the object you want to upload to OSS, and must include the file extension of the object. For example, set <yourObjectName> to abc/efg/123.jpg.
String objectName = "<yourObjectName>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Create an InitiateMultipartUploadRequest object.
InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest("<yourBucketName>", "<yourObjectName>");

// Optional. Specify the storage class.
// ObjectMetadata metadata = new ObjectMetadata();
// metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
// request.setObjectMetadata(metadata);

// Initiate a multipart upload task.
InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
// Obtain an upload ID. The upload ID is the unique identification of a multipart upload task. You can initiate related operations such as canceling multipart upload and querying multipart upload based on the upload ID.
String uploadId = upresult.getUploadId();

// partETags is a set of ETags of parts. A PartETag consists of an ETag and a part number.
List<PartETag> partETags =  new ArrayList<PartETag>();
// Calculate the total number of upload parts.
final long partSize = 1 * 1024 * 1024L;   // 1MB
final File sampleFile = new File("<localFile>");
long fileLength = sampleFile.length();
int partCount = (int) (fileLength / partSize);
if (fileLength % partSize ! = 0) {
    partCount++;
 }
// Upload each part until all parts are uploaded.
for (int i = 0; i < partCount; i++) {
    long startPos = i * partSize;
    long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
    InputStream instream = new FileInputStream(sampleFile);
    // Skip the parts that have been uploaded.
    instream.skip(startPos);
    UploadPartRequest uploadPartRequest = new UploadPartRequest();
    uploadPartRequest.setBucketName(bucketName);
    uploadPartRequest.setKey(objectName);
    uploadPartRequest.setUploadId(uploadId);
    uploadPartRequest.setInputStream(instream);
    // Configure the size of each part. All parts are at least 100 KB except for the last part. This limit does not apply to the last part.
    uploadPartRequest.setPartSize(curPartSize);
    // Configure part numbers. Each part is configured with a part number. The value can be from 1 to 10000. If you configure a number beyond this range, OSS returns an InvalidArgument error code.
    uploadPartRequest.setPartNumber( i + 1);
    // Parts are not necessarily uploaded in order. They can be uploaded from different OSS clients. OSS sorts the parts based on their part numbers and combines them to obtain a complete object.
    UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
    // When you have uploaded a part, OSS returns a result that contains a PartETag. The PartETag is stored in partETags.
    partETags.add(uploadPartResult.getPartETag());
}


// Create a CompleteMultipartUploadRequest object.
// When you have completed multipart upload, you must provide all valid partETags. After receiving the partETags, OSS verifies the validity of all parts one by one. If part verification is successful, OSS combines these parts into a complete object.
CompleteMultipartUploadRequest completeMultipartUploadRequest =
        new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);

// Optional. Set the ACL.
// completeMultipartUploadRequest.setObjectACL(CannedAccessControlList.PublicRead);

// Complete multipart upload.
CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);

// Shut down the OSSClient instance.
ossClient.shutdown();

Cancel a multipart upload task

You can use the ossClient.abortMultipartUpload method to cancel a multipart upload task. If a multipart upload task is canceled, the upload ID can no longer be used to perform further operations. The parts uploaded with that upload ID are also deleted.

The following code provides an example on how to cancel a multipart upload task:

// This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Cancel the multipart upload task. The upload ID is returned by InitiateMultipartUpload.
AbortMultipartUploadRequest abortMultipartUploadRequest =
        new AbortMultipartUploadRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
ossClient.abortMultipartUpload(abortMultipartUploadRequest);

// Shut down the OSSClient instance.
ossClient.shutdown();
			

List uploaded parts

You can use the ossClient.listParts method to list all parts that are uploaded with the specified upload ID.

  • Simple list

    The following code provides an example for simple list:

    // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // List uploaded parts. The upload ID is returned by InitiateMultipartUpload.
    ListPartsRequest listPartsRequest = new ListPartsRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
     // Configure an upload ID.
     //listPartsRequest.setUploadId(uploadId);
     // Set the maximum number of parts to list on each page to 100. By default, 1,000 tasks are listed.
     listPartsRequest.setMaxParts(100);
     // Specify the start point of the list. Only the parts with part numbers greater than the value of this parameter are listed.
     listPartsRequest.setPartNumberMarker(2);
    PartListing partListing = ossClient.listParts(listPartsRequest);
    
    for (PartSummary part : partListing.getParts()) {
        // Obtain part numbers.
        part.getPartNumber();
        // Obtain the part size.
        part.getSize();
        // Obtain the ETag.
        part.getETag();
        // Obtain the last modification time.
        part.getLastModified();
    }
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
    					
  • List all uploaded parts

    By default, listParts can list up to 1,000 parts at a time. The following code provides an example on how to list more than 1,000 parts:

    // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // List all uploaded parts.
    PartListing partListing;
    ListPartsRequest listPartsRequest = new ListPartsRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
    
    do {
        partListing = ossClient.listParts(listPartsRequest);
    
        for (PartSummary part : partListing.getParts()) {
            // Obtain part numbers.
            part.getPartNumber();
            // Obtain the part size.
            part.getSize();
            // Obtain the ETag.
            part.getETag();
            // Obtain the last modification time.
            part.getLastModified();
        }
    // Specify the start point of the list. Only the parts with part numbers greater than the value of this parameter are listed.
    listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
    } while (partListing.isTruncated());
    
    // Shut down the OSSClient instance.
    ossClient.shutdown()
    					
  • List all uploaded parts by page

    The following code provides an example on how to specify the maximum number of parts to list on each page and list all uploaded parts by page:

    // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // List all uploaded parts by page.
    PartListing partListing;
    ListPartsRequest listPartsRequest = new ListPartsRequest("<yourBucketName>", "<yourObjectName>", "<uploadId>");
    // Set the maximum number of parts to list on each page to 100.
    listPartsRequest.setMaxParts(100);
    
    do {
        partListing = ossClient.listParts(listPartsRequest);
    
        for (PartSummary part : partListing.getParts()) {
            // Obtain part numbers.
            part.getPartNumber();
            // Obtain the part size.
            part.getSize();
            // Obtain the ETag.
            part.getETag();
            // Obtain the last modification time.
            part.getLastModified();
        }
    
        listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
    
    } while (partListing.isTruncated());
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
    					

List multipart upload tasks

You can use the ossClient.listMultipartUploads method to list all ongoing multipart upload tasks (tasks that have been initiated but not completed or tasks that have been canceled). The following table describes the parameters.

Parameter Description Configuration method
prefix Specifies the prefix that returned object names must contain. Note that if you use a prefix for a query, the returned object name contains the prefix. ListMultipartUploadsRequest.setPrefix(String prefix)
delimiter Groups objects by name. The substring between the specified prefix and the occurrence of the first delimiter is commonPrefixes. A substring of object names starts with the prefix and ends with the next occurrence of the specified delimiter. ListMultipartUploadsRequest.setDelimiter(String delimiter)
maxUploads Specifies the maximum number of multipart upload tasks returned at a time. The default value is 1000. The maximum value is 1000. ListMultipartUploadsRequest.setMaxUploads(Integer maxUploads)
keyMarker Specifies the name of the object after which the listing of multipart upload tasks begins. All multipart upload tasks with objects whose names start with a letter that comes after the keyMarker parameter value in alphabetical order are listed. You can use this parameter with the uploadIdMarker parameter to specify the start point to list the returned results. ListMultipartUploadsRequest.setKeyMarker(String keyMarker)
uploadIdMarker UploadIdMarker is used with the keyMarker parameter to specify the start point to list the returned results. If the keyMarker parameter is not configured, the uploadIdMarker parameter is invalid. If the keyMarker parameter is configured, the query result includes:
  • All objects whose names start with a letter that comes after the keyMarker parameter value in alphabetical order.
  • All objects whose names start with a letter that is the same as the keyMarker parameter value in alphabetical order and of which the uploadId parameter value is greater than the uploadIdMarker parameter value.
ListMultipartUploadsRequest.setUploadIdMarker(String uploadIdMarker)
  • Simple list

    The following code provides an example for simple list:

    // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // List multipart upload tasks. By default, 1,000 tasks are listed.
    ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
    MultipartUploadListing multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
    
    for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
        // Obtain upload IDs.
        multipartUpload.getUploadId();
        // Obtain object names.
        multipartUpload.getKey();
        // Obtain the time the multipart upload tasks are initiated.
        multipartUpload.getInitiated();
    }
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
    					

    If the value of the isTruncated field in the returned result is false, values of nextKeyMarker and nextUploadIdMarker are returned and used as the start point for the next object reading. If all multipart upload tasks cannot be returned at a time, list them by page.

  • List all multipart upload tasks

    By default, listMultipartUploads can list up to 1,000 multipart upload tasks at a time. The following code provides an example on how to list more than 1,000 multipart upload tasks:

    // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // List multipart upload tasks.
    MultipartUploadListing multipartUploadListing;
    ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
    
    do {
        multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
    
        for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
            // Obtain upload IDs.
            multipartUpload.getUploadId();
            // Obtain object names.
            multipartUpload.getKey();
            // Obtain the time the multipart upload tasks are initiated.
            multipartUpload.getInitiated();
        }
    
        listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
    
        listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
    } while (multipartUploadListing.isTruncated());
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
    					
  • List all multipart upload tasks by page

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

    // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // List multipart upload tasks.
    MultipartUploadListing multipartUploadListing;
    ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
    // Specify the number of multipart upload tasks to list on each page.
    listMultipartUploadsRequest.setMaxUploads(50);
    
    do {
        multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
    
        for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
            // Obtain upload IDs.
            multipartUpload.getUploadId();
            // Obtain object names.
            multipartUpload.getKey();
            // Obtain the time the multipart upload tasks are initiated.
            multipartUpload.getInitiated();
        }
    
        listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
        listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
    
    } while (multipartUploadListing.isTruncated());
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();