All Products
Search
Document Center

Object Storage Service:Multipart upload

Last Updated:Jan 12, 2024

Object Storage Service (OSS) provides the multipart upload feature. Multipart upload allows you to split a large object into multiple parts to upload. After these parts are uploaded, you can call the CompleteMultipartUpload operation to combine the parts into a complete object.

Usage notes

  • Before you use the multipart upload feature, make sure that you familiarize yourself with this feature. For more information, see Multipart upload.

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about the regions and endpoints supported by OSS, see Regions and endpoints.

  • In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.

  • In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Create an OSSClient instance.

  • To perform multipart upload, you must have the oss:PutObject permission. For more information, see Attach a custom policy to a RAM user.

Procedure

To upload an object by using multipart upload, perform the following steps:

  1. Initialize a multipart upload task.

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

  2. Upload parts.

    Call the ossClient.uploadPart method to upload the parts.

    Note
    • If parts are uploaded by a multipart upload task that has a specific upload ID, part numbers are used to identify the relative positions of the parts in an object. If you upload a part that has the same part number as an existing part, the existing part is overwritten by the uploaded part.

    • OSS includes the MD5 hash of each uploaded part in the ETag header in the response.

    • OSS calculates the MD5 hash of uploaded data and compares the MD5 hash with the MD5 hash that is calculated by OSS SDK for Java. If the two hashes are different, OSS returns the InvalidDigest error code.

  3. Complete the multipart upload task.

    After all parts are uploaded, call the ossClient.completeMultipartUpload method to combine these parts into a complete object.

For more information about multipart upload and its scenarios, see Multipart upload.

Sample code of multipart upload

The following sample code provides an example on how to implement a multipart upload task by following the multipart upload process:

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.internal.Mimetypes;
import com.aliyun.oss.model.*;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

public class Demo {

    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
        String objectName = "exampledir/exampleobject.txt";
        // Specify the path of the local file that you want to upload. 
        String filePath = "D:\\localpath\\examplefile.txt";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
        try {
            // Create an InitiateMultipartUploadRequest object. 
            InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);

            // The following code provides an example on how to specify the request headers when you initiate a multipart upload task: 
             ObjectMetadata metadata = new ObjectMetadata();
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
            // Specify the caching behavior of the web page for the object. 
            // metadata.setCacheControl("no-cache");
            // Specify the name of the object when the object is downloaded. 
            // metadata.setContentDisposition("attachment;filename=oss_MultipartUpload.txt");
            // Specify the encoding format for the content of the object. 
            // metadata.setContentEncoding(OSSConstants.DEFAULT_CHARSET_NAME);
            // Specify whether existing objects are overwritten by objects that have the same names when the multipart upload task is initiated. In this example, this parameter is set to true, which indicates that an existing object with the same name as the object to upload is not overwritten. 
            // metadata.setHeader("x-oss-forbid-overwrite", "true");
            // Specify the server-side encryption method that you want to use to encrypt each part of the object that you want to upload. 
            // metadata.setHeader(OSSHeaders.OSS_SERVER_SIDE_ENCRYPTION, ObjectMetadata.KMS_SERVER_SIDE_ENCRYPTION);
            // Specify the algorithm that is used to encrypt the object. If you do not configure this parameter, the object is encrypted by using AES-256. 
            // metadata.setHeader(OSSHeaders.OSS_SERVER_SIDE_DATA_ENCRYPTION, ObjectMetadata.KMS_SERVER_SIDE_ENCRYPTION);
            // Specify the ID of the customer master key (CMK) that is managed by Key Management Service (KMS). 
            // metadata.setHeader(OSSHeaders.OSS_SERVER_SIDE_ENCRYPTION_KEY_ID, "9468da86-3509-4f8d-a61e-6eab1eac****");
            // Specify the storage class of the object. 
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard);
            // Specify tags for the object. You can specify multiple tags for the object at a time. 
            // metadata.setHeader(OSSHeaders.OSS_TAGGING, "a:1");
            // request.setObjectMetadata(metadata);

            // Specify ContentType based on the object type. If you do not specify this parameter, the default value of the ContentType field is application/oct-srream. 
            if (metadata.getContentType() == null) {
                metadata.setContentType(Mimetypes.getInstance().getMimetype(new File(filePath), objectName));
            }

            // Initiate a multipart upload task. 
            InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
            // Obtain the upload ID. 
            String uploadId = upresult.getUploadId();
            // Cancel the multipart upload task or list uploaded parts based on the upload ID. 
            // If you want to cancel a multipart upload task based on the upload ID, obtain the upload ID after you call the InitiateMultipartUpload operation to initiate the multipart upload task.  
            // If you want to list the uploaded parts in a multipart upload task based on the upload ID, obtain the upload ID after you call the InitiateMultipartUpload operation to initiate the multipart upload task and before you call the CompleteMultipartUpload operation to complete the multipart upload task. 
            // System.out.println(uploadId);

            // partETags is a set of PartETags. A PartETag consists of the part number and ETag of an uploaded part. 
            List<PartETag> partETags =  new ArrayList<PartETag>();
            // Specify the size of each part. The part size is used to calculate the number of parts of the object. Unit: bytes. 
            final long partSize = 1 * 1024 * 1024L; // Set the part size to 1 MB. 

            // Calculate the number of parts based on the size of the uploaded data. In the following code, a local file is used as an example to show how to use the File.length() method to obtain the size of the uploaded data. 
            final File sampleFile = new File(filePath);
            long fileLength = sampleFile.length();
            int partCount = (int) (fileLength / partSize);
            if (fileLength % partSize != 0) {
                partCount++;
            }
            // Upload all parts. 
            for (int i = 0; i < partCount; i++) {
                long startPos = i * partSize;
                long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
                UploadPartRequest uploadPartRequest = new UploadPartRequest();
                uploadPartRequest.setBucketName(bucketName);
                uploadPartRequest.setKey(objectName);
                uploadPartRequest.setUploadId(uploadId);
                // Specify the input stream of the multipart upload task. 
                // In the following code, a local file is used as an example to show how to create a FIleInputstream and use the InputStream.skip() method to skip the specified data. 
                InputStream instream = new FileInputStream(sampleFile);
                instream.skip(startPos);
                uploadPartRequest.setInputStream(instream);
                // Specify the part size. Each part except the last part must be equal to or greater than 100 KB in size. 
                uploadPartRequest.setPartSize(curPartSize);
                // Set part numbers. Each part has a part number that ranges from 1 to 10,000. If the number that you specify does not fall within the range, OSS returns the InvalidArgument error code. 
                uploadPartRequest.setPartNumber( i + 1);
                // Parts are not uploaded in sequence. Parts can be uploaded from different OSS clients. OSS sorts the parts based on the part number and then combines the parts to obtain a complete object. 
                UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
                // When a part is uploaded, OSS returns a result that contains a PartETag. The PartETag is stored in partETags. 
                partETags.add(uploadPartResult.getPartETag());
            }


            // Create a CompleteMultipartUploadRequest object. 
            // When you call the CompleteMultipartUpload operation, you must provide all valid PartETags. After OSS receives the partETags, OSS verifies all parts one by one. After all parts are verified, OSS combines these parts into a complete object. 
            CompleteMultipartUploadRequest completeMultipartUploadRequest =
                    new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);

            // The following code provides an example on how to configure the access control list (ACL) of the object when the multipart upload task is completed: 
            // completeMultipartUploadRequest.setObjectACL(CannedAccessControlList.Private);
            // Specify whether to list all parts that are uploaded by using the current upload ID. For OSS SDK for Java 3.14.0 and later, you can set partETags in CompleteMultipartUploadRequest to null only when you list all parts uploaded to the OSS server to combine the parts into a complete object. 
            // Map<String, String> headers = new HashMap<String, String>();
            // If you set x-oss-complete-all to yes in the request, OSS lists all parts that are uploaded by using the current upload ID, sorts the parts by part number, and then performs the CompleteMultipartUpload operation. 
            // If you set x-oss-complete-all to yes in the request, the request body cannot be specified. If you specify the request body, an error is reported. 
            // headers.put("x-oss-complete-all","yes");
            // completeMultipartUploadRequest.setHeaders(headers);

            // Complete the multipart upload task. 
            CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
            System.out.println(completeMultipartUploadResult.getETag());
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Cancel a multipart upload task

You can call the ossClient.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 sample code provides an example on how to cancel a multipart upload task:

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
        String objectName = "exampledir/exampleobject.txt";
        // Specify the upload ID. Example: 0004B999EF518A1FE585B0C9360D****. You can obtain the upload ID from the response to the InitiateMultipartUpload operation. 
        String uploadId = "0004B999EF518A1FE585B0C9360D****";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
        try {
            // Cancel the multipart upload task. 
            AbortMultipartUploadRequest abortMultipartUploadRequest =
                    new AbortMultipartUploadRequest(bucketName, objectName, uploadId);
            ossClient.abortMultipartUpload(abortMultipartUploadRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

List uploaded parts

You can call the ossClient.listParts method to list all parts that are uploaded by using a specific upload ID.

  • List uploaded parts by using simple list

    The following code provides an example on how to use simple list to list uploaded parts:

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.common.auth.*;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    
    public class Demo {
    
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
            EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
            // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
            String objectName = "exampledir/exampleobject.txt";
            // Specify the upload ID. Example: 0004B999EF518A1FE585B0C9360D****. You can obtain the upload ID from the response to the InitiateMultipartUpload operation. You must obtain the upload ID before you call the CompleteMultipartUpload operation to complete the multipart upload task. 
            String uploadId = "0004B999EF518A1FE585B0C9360D****";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
            try {
                // List uploaded parts. 
                ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId);
                // Specify the upload ID. 
                //listPartsRequest.setUploadId(uploadId);
                // Set the maximum number of parts that can be displayed on each page to 100. By default, 1,000 parts are listed. 
                listPartsRequest.setMaxParts(100);
                // Specify the position from which the list operation starts. Only the parts whose part numbers are greater than the value of this parameter are listed. 
                listPartsRequest.setPartNumberMarker(2);
                PartListing partListing = ossClient.listParts(listPartsRequest);
    
                for (PartSummary part : partListing.getParts()) {
                    // Obtain the part numbers. 
                    System.out.println(part.getPartNumber());
                    // Obtain the size of each part. 
                    System.out.println(part.getSize());
                    // Obtain the ETag of each part. 
                    System.out.println(part.getETag());
                    // Obtain the last modification time of each part. 
                    System.out.println(part.getLastModified());
                }
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }
  • List all uploaded parts

    By default, you can list up to 1,000 uploaded parts at the same time by using listParts. If you want to list more than 1,000 uploaded parts, use the following code.

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.common.auth.*;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    
    public class Demo {
    
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
            EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
            // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
            String objectName = "exampledir/exampleobject.txt";
            // Specify the upload ID. Example: 0004B999EF518A1FE585B0C9360D****. You can obtain the upload ID from the response to the InitiateMultipartUpload operation. You must obtain the upload ID before you call the CompleteMultipartUpload operation to complete the multipart upload task. 
            String uploadId = "0004B999EF518A1FE585B0C9360D****";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
            try {
                // List all uploaded parts. 
                PartListing partListing;
                ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId);
    
                do {
                    partListing = ossClient.listParts(listPartsRequest);
    
                    for (PartSummary part : partListing.getParts()) {
                        // Obtain the part numbers. 
                        System.out.println(part.getPartNumber());
                        // Obtain the size of each part. 
                        System.out.println(part.getSize());
                        // Obtain the ETag of each part. 
                        System.out.println(part.getETag());
                        // Obtain the last modification time of each part. 
                        System.out.println(part.getLastModified());
                    }
                    // Specify the position from which the list operation starts. Only the parts whose part numbers are greater than the value of this parameter are listed. 
                    listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
                } while (partListing.isTruncated());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }
  • List all uploaded parts by page

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

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.common.auth.*;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    
    public class Demo {
    
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
            EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
            // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
            String objectName = "exampledir/exampleobject.txt";
            // Specify the upload ID. Example: 0004B999EF518A1FE585B0C9360D****. You can obtain the upload ID from the response to the InitiateMultipartUpload operation. You must obtain the upload ID before you call the CompleteMultipartUpload operation to complete the multipart upload task. 
            String uploadId = "0004B999EF518A1FE585B0C9360D****";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
            try {
                // List all uploaded parts by page. 
                PartListing partListing;
                ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId);
                // Set the maximum number of parts to list per page to 100. 
                listPartsRequest.setMaxParts(100);
    
                do {
                    partListing = ossClient.listParts(listPartsRequest);
    
                    for (PartSummary part : partListing.getParts()) {
                        // Obtain the part numbers. 
                        System.out.println(part.getPartNumber());
                        // Obtain the size of each part. 
                        System.out.println(part.getSize());
                        // Obtain the ETag of each part. 
                        System.out.println(part.getETag());
                        // Obtain the last modification time of each part. 
                        System.out.println(part.getLastModified());
                    }
    
                    listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
    
                } while (partListing.isTruncated());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }                    

List multipart upload tasks

You can call the ossClient.listMultipartUploads method to list all ongoing multipart upload tasks. Ongoing multipart upload tasks refer to tasks that have been initiated but are not completed or canceled. The following table describes the parameters that you can configure to list these tasks.

Parameter

Description

Method

prefix

The prefix that the names of returned objects must contain. If you use a prefix for a query, the returned object names contain the prefix.

ListMultipartUploadsRequest.setPrefix(String prefix)

delimiter

The character used to group object names. Objects whose names contain a substring from the specified prefix to the first occurrence of the delimiter are returned as a single element.

ListMultipartUploadsRequest.setDelimiter(String delimiter)

maxUploads

The maximum number of multipart upload tasks that you want to return for the current list operation. Maximum value: 1000. Default value: 1000.

ListMultipartUploadsRequest.setMaxUploads(Integer maxUploads)

keyMarker

Specifies that all multipart upload tasks with objects whose names are alphabetically after the value of the keyMarker parameter are included in the list. You can use this parameter together with the uploadIdMarker parameter to specify the position from which the returned results start.

ListMultipartUploadsRequest.setKeyMarker(String keyMarker)

uploadIdMarker

The position from which the returned results start. You can use this parameter together with the keyMarker parameter. If you do not configure the keyMarker parameter, the uploadIdMarker parameter is invalid. If you configure the keyMarker parameter, the query results include the following items:

  • All objects whose names are lexicographically after the value of the keyMarker parameter.

  • All multipart upload tasks with objects whose names are the same as the value of the keyMarker parameter. The upload IDs of the multipart upload tasks must be greater than the value of the uploadIdMarker parameter.

ListMultipartUploadsRequest.setUploadIdMarker(String uploadIdMarker)

  • List multipart upload tasks by using simple list

    The following sample code provides an example on how to use simple list to list multipart upload tasks:

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.common.auth.*;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    
    public class Demo {
    
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
            EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
            try {
                // List multipart upload tasks. By default, 1,000 parts are listed. 
                ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
                MultipartUploadListing multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
    
                for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
                    // Obtain the upload ID of each multipart upload task. 
                    System.out.println(multipartUpload.getUploadId());
                    // Obtain the name of each multipart upload task. 
                    System.out.println(multipartUpload.getKey());
                    // Obtain the point in time when each multipart upload task is initiated. 
                    System.out.println(multipartUpload.getInitiated());
                }
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }

    If the value of the isTruncated parameter in the response is true, the values of nextKeyMarker and nextUploadIdMarker are returned to specify the position from which the next read operation starts. If the response does not contain all multipart upload tasks, list multipart upload tasks by page.

  • List all multipart upload tasks

    By default, you can use the listMultipartUploads operation to list up to 1,000 parts at a time. The following sample code provides an example on how to list all multipart upload tasks when the number of parts is greater than 1,000:

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.common.auth.*;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    
    public class Demo {
    
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
            EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
            try {
                // List multipart upload tasks. 
                MultipartUploadListing multipartUploadListing;
                ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
    
                do {
                    multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);
    
                    for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
                        // Obtain the upload ID of each multipart upload task. 
                        System.out.println(multipartUpload.getUploadId());
                        // Obtain the object name. 
                        System.out.println(multipartUpload.getKey());
                        // Obtain the point in time when each multipart upload task is initiated. 
                        System.out.println(multipartUpload.getInitiated());
                    }
    
                    listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
    
                    listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
                } while (multipartUploadListing.isTruncated());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    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:

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.common.auth.*;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    
    public class Demo {
    
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
            EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
            try {
                // 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 the upload ID of each multipart upload task. 
                        System.out.println(multipartUpload.getUploadId());
                        // Obtain the name of each multipart upload task. 
                        System.out.println(multipartUpload.getKey());
                        // Obtain the point in time when each multipart upload task is initiated. 
                        System.out.println(multipartUpload.getInitiated());
                    }
    
                    listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
                    listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
    
                } while (multipartUploadListing.isTruncated());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }

References

  • For the complete sample code that is used to perform multipart upload, visit GitHub.

  • A multipart upload involves three API operations. For more information about the operations, 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 are tasks that have been initiated but are not completed or canceled.