Updated on 2024-06-18 GMT+08:00

Assembling Parts (SDK for Java)

Function

This API assembles the uploaded parts to compete the multipart upload. Before performing this operation, you cannot download the uploaded data. When assembling parts, you need to copy the additional message header information recorded during the multipart upload initiation to the object metadata. Such information is processed the same way the information in a common object upload is processed. In the case of assembling parts concurrently, last write wins is applied, but the time of last write is defined as the time when a multipart upload was initiated.

The uploaded parts occupy your storage as long as the multipart upload has not been aborted. You can assemble all or some of the uploaded parts to complete the multipart upload. Once the multipart upload is complete, the parts that are not assembled will be deleted and no longer occupy storage.

When assembling parts, OBS creates an object by putting part numbers in ascending order. If any object metadata is provided in the initiation of the multipart upload, OBS will associate the metadata with the object. After the multipart upload is complete, the parts will no longer exist. A part assembling request must contain the upload ID, part numbers, and a list of corresponding ETag values. In response to the request, the ETag that uniquely identifies the assembled parts is contained. This ETag is not the MD5 hash value of the entire object.

Restrictions

  • To assemble parts, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
  • After a multipart upload is complete, the uploaded parts that are not assembled will be automatically deleted and cannot be recovered. Before assembling parts, use the API for listing uploaded parts to check all parts to ensure that no part is missed.

Method

obsClient.completeMultipartUpload(CompleteMultipartUploadRequest request)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

request

CompleteMultipartUploadRequest

Yes

Explanation:

Request parameters for assembling parts. For details, see Table 2.

Table 2 CompleteMultipartUploadRequest

Parameter

Type

Mandatory (Yes/No)

Description

bucketName

String

Yes

Explanation:

Bucket name.

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

objectKey

String

Yes

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.eu-west-101.myhuaweicloud.eu/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

partEtag

List<PartEtag>

Yes

Explanation:

List of parts to be assembled. For details, see Table 3.

uploadId

String

Yes

Explanation:

Multipart upload ID, for example, 000001648453845DBB78F2340DD460D8.

Value range:

The value must contain 32 characters.

Default value:

None

encodingType

String

No

Explanation:

Encoding type for objectKey in the response. If objectKey in the response contains control characters that are not supported by the XML 1.0 standard, you can specify this parameter to encode objectKey.

Value range:

url

Default value:

None. If you leave this parameter blank, encoding is not applied.

userHeaders

HashMap<String, String>

No

Explanation:

User header list. In HashMap, the String key and value indicate the name and value of the user header field respectively. The SDK does not process the userHeaders and instead transparently transmits it to the server for later use.

Default value:

None

Table 3 PartEtag

Parameter

Type

Mandatory (Yes/No)

Description

etag

String

Yes

Explanation:

Part ETag. Base64-encoded, 128-bit MD5 value of the part.

Value range:

The value must contain 32 characters.

Default value:

None

partNumber

Integer

Yes

Explanation:

Part number. Part numbers can be inconsecutive.

Value range:

An integer ranging from 1 to 10000.

Default value:

None

Responses

Table 4 CompleteMultipartUploadResult

Parameter

Type

Description

statusCode

int

Explanation:

HTTP status code.

Value range:

A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response.

For more information, see Status Code.

Default value:

None

responseHeaders

Map<String, Object>

Explanation:

Response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header.

Default value:

None

etag

String

Explanation:

Base64-encoded, 128-bit MD5 value of an object. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, the object content is changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

Restrictions:

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

Value range:

The value must contain 32 characters.

Default value:

None

bucketName

String

Explanation:

Bucket in which parts are assembled.

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

objectKey

String

Explanation:

The name of the object the parts are assembled into.

An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.eu-west-101.myhuaweicloud.eu/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

location

String

Explanation:

URL of the object the parts are assembled into.

Example: https://example-Bucket.obs.regions.myhuaweicloud.eu/example-Object.

Default value:

None

versionId

String

Explanation:

Version ID of the object the parts are assembled into. If versioning is enabled for the bucket, the object version number will be returned.

Value range:

The value must contain 32 characters.

Default value:

None

objectUrl

String

Explanation:

Full path to the object the parts are assembled into.

Default value:

None

encodingType

String

Explanation:

Encoding type for objectKey in the response. If objectKey in the response contains control characters that are not supported by the XML 1.0 standard, you can specify this parameter to encode objectKey.

Value range:

url

Default value:

None. If you leave this parameter blank, encoding is not applied.

Code Examples

This example calls ObsClient.completeMultipartUpload to assemble parts into object objectname in bucket examplebucket based on uploadId and partEtags.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.CompleteMultipartUploadRequest;
import com.obs.services.model.PartEtag;
import java.util.ArrayList;
import java.util.List;
public class CompleteMultipartUpload001 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one in your actual situation.
        String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu"; 
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
        
        // Create an ObsClient instance.
        // Use the permanent AK/SK pair to initialize the client.
        ObsClient obsClient = new ObsClient(ak, sk,endPoint);
        // Use the temporary AK/SK pair and security token to initialize the client.
        // ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);

        try {
            String uploadId = "upload id from initiateMultipartUpload";
            List<PartEtag> partEtags = new ArrayList<PartEtag>();
            // First part
            PartEtag part1 = new PartEtag();
            part1.setPartNumber(1);
            part1.seteTag("etag1");
            partEtags.add(part1);
            // Second part
            PartEtag part2 = new PartEtag();
            part2.setPartNumber(2);
            part2.setEtag("etag2");
            partEtags.add(part2);
            CompleteMultipartUploadRequest request =
                    new CompleteMultipartUploadRequest("examplebucket", "objectname", uploadId, partEtags);
            obsClient.completeMultipartUpload(request);
            System.out.println("completeMultipartUpload successfully");
        } catch (ObsException e) {
            System.out.println("CompleteMultipartUpload failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code:" + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message:" + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
            e.printStackTrace();
        } catch (Exception e) {
            System.out.println("completeMultipartUpload failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}