Object Storage Service (OSS) provides a multipart upload feature for large objects. This process involves splitting a large object into smaller parts, uploading them independently, and then calling the CompleteMultipartUpload API to combine the parts into a single object. This enables resumable uploads.
Notes
-
In this topic, the public endpoint of the China (Hangzhou) region is used. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For details about supported regions and endpoints, see Regions and Endpoints.
-
In this topic, access credentials are obtained from environment variables. For more information, see Configure access credentials.
-
This topic demonstrates creating an OSSClient instance with an OSS endpoint. For alternative configurations, such as using a custom domain or authenticating with credentials from Security Token Service (STS), see Client configuration.
-
Multipart upload uses InitiateMultipartUpload, UploadPart, and CompleteMultipartUpload. You must have the
oss:PutObjectpermission. Grant custom access policies to a RAM user.
Multipart upload process
Multipart upload involves three steps:
-
Initialize a multipart upload.
Call ossClient.initiateMultipartUpload. OSS returns a globally unique upload ID.
-
Upload parts.
Call ossClient.uploadPart to upload part data.
Note-
The part number identifies the position of a part within the object. Uploading data with the same part number overwrites the existing part.
-
OSS returns the MD5 hash of received part data in the response ETag header.
-
OSS calculates the MD5 hash of uploaded data and compares it with the hash calculated by the SDK. A mismatch returns the InvalidDigest error code.
-
-
Complete the multipart upload.
After all parts are uploaded, call ossClient.completeMultipartUpload to merge the parts into a complete object.
Example code
The following example shows the complete multipart upload process:
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
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 {
// Use the endpoint of the China (Hangzhou) region as an example. Specify the 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 bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
// The path of the local file to upload.
String filePath = "D:\\localpath\\examplefile.txt";
// Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou.
String region = "cn-hangzhou";
// Create an OSSClient instance.
// When the OSSClient instance is no longer used, call the shutdown method to release resources.
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// Create an InitiateMultipartUploadRequest object.
InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);
// Create an ObjectMetadata object and set the Content-Type.
ObjectMetadata metadata = new ObjectMetadata();
if (metadata.getContentType() == null) {
metadata.setContentType(Mimetypes.getInstance().getMimetype(new File(filePath), objectName));
}
System.out.println("Content-Type: " + metadata.getContentType());
// Bind the metadata to the upload request.
request.setObjectMetadata(metadata);
// Initialize the multipart upload.
InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
// Return the upload ID.
String uploadId = upresult.getUploadId();
// partETags is a collection of PartETag objects. A PartETag object consists of the ETag and part number of a part.
List<PartETag> partETags = new ArrayList<PartETag>();
// The size of each part. This is used to calculate the number of parts. Unit: bytes.
// The minimum part size is 100 KB, and the maximum part size is 5 GB. The size of the last part can be smaller than 100 KB.
// Set the part size to 1 MB.
final long partSize = 1 * 1024 * 1024L;
// Calculate the number of parts based on the size of the data to upload. The following code provides an example of how to obtain the size of the data to upload from a local file using File.length().
final File sampleFile = new File(filePath);
long fileLength = sampleFile.length();
int partCount = (int) (fileLength / partSize);
if (fileLength % partSize != 0) {
partCount++;
}
// Traverse the parts and upload them.
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);
// Set the stream of the part to upload.
// The following code provides an example of how to create a FileInputStream object from a local file and skip the specified data using the InputStream.skip() method.
InputStream instream = new FileInputStream(sampleFile);
instream.skip(startPos);
uploadPartRequest.setInputStream(instream);
// Set the part size.
uploadPartRequest.setPartSize(curPartSize);
// Set the part number. Each uploaded part has a part number that ranges from 1 to 10,000. If the part number is not in the range, OSS returns the InvalidArgument error code.
uploadPartRequest.setPartNumber(i + 1);
// Parts do not need to be uploaded in sequence. They can even be uploaded from different clients. OSS sorts the parts by part number to create a complete object.
UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
// After each part is uploaded, the OSS response includes a PartETag. The PartETag is saved in partETags.
partETags.add(uploadPartResult.getPartETag());
// Close the stream.
instream.close();
}
// Create a CompleteMultipartUploadRequest object.
// When you complete the multipart upload, you must provide all valid partETags. After OSS receives the submitted partETags, it verifies the validity of each part. After all parts are verified, OSS combines these parts into a complete object.
CompleteMultipartUploadRequest completeMultipartUploadRequest =
new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);
// Complete the multipart upload.
CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
System.out.println("Upload successful, ETag: " + 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 a 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();
}
}
}
}Common scenarios
Set metadata when you initialize a multipart upload
Set object access permissions when you complete a multipart upload
Automatically process part ETags when you complete a multipart upload
Cancel a multipart upload event
List uploaded parts
List multipart upload events
Perform multipart upload for network streams or data streams
References
-
Complete sample code: GitHub example.
-
A multipart upload involves three API operations:
-
Initialize a multipart upload: InitiateMultipartUpload.
-
Upload a part: UploadPart.
-
Complete a multipart upload: CompleteMultipartUpload.
-
-
Cancel a multipart upload: AbortMultipartUpload.
-
List uploaded parts: ListParts.
-
List in-progress multipart uploads: ListMultipartUploads.