Help Center/ Object Storage Service/ SDK Reference/ Node.js/ Multipart Upload (SDK for Node.js)/ Assembling Parts (SDK for Node.js)
Updated on 2024-11-13 GMT+08:00
View PDF
Share

Assembling Parts (SDK for Node.js)

If you have any questions during development, post them on the Issues page of GitHub.

Function

This API assembles the uploaded parts to complete 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 in the same way the information in a regular object upload is processed. In the case of assembling parts concurrently, the Last Write Wins strategy applies, 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, parts that have not been assembled will be deleted and no longer occupy storage.

When assembling parts, OBS arranges parts in ascending order by part number. If any object metadata is provided during the initiation of the multipart upload, OBS will associate this metadata with the object. When the multipart upload is complete, the individual parts will no longer exist. A part assembling request must contain the upload ID, part numbers, and ETag values. OBS responses include the ETag that uniquely identifies the object data. This ETag is not required to be the MD5 hash value of the object data.

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.
  • To learn about the mappings between OBS regions and endpoints, see Regions and Endpoints.
  • After a multipart upload is complete, the uploaded parts that were not assembled will be automatically deleted and cannot be restored. Before assembling parts, use the API for listing uploaded parts to check all parts to ensure no parts were left out.
  • If the size of any part other than the last part is smaller than 100 KB, OBS returns 400 Bad Request.

Method

ObsClient.completeMultipartUpload(params)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

Bucket

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 a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets with 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.

Value range:

The value can contain 3 to 63 characters.

Default value:

None

Key

string

Yes

Explanation:

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

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Restrictions:

None

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

UploadId

string

Yes

Explanation:

Multipart upload ID, which is generated by initiating a multipart upload.

Restrictions:

None

Value range:

The value must contain 32 characters, for example, 000001648453845DBB78F2340DD460D8.

Default value:

None

Parts

Part[]

Yes

Explanation:

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

EncodingType

string

No

Explanation:

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

Value range:

url

Default value:

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

Parameter

Type

Description

PartNumber

number

Explanation:

Part number.

Restrictions:

None

Value range:

An integer ranging from 1 to 10000.

Default value:

None

ETag

string

Explanation:

ETag of a part. It is calculated by encoding the 128-bit MD5 value of the part using Base64.

Restrictions:

ETag (MD5 value of the part data) can be obtained from the response returned by the API for uploading a part.

Value range:

The value must contain 32 characters.

Default value:

None

Responses

Table 3 Responses

Type

Description

Table 4

NOTE:

This API returns a Promise response, which requires the Promise or async/await syntax.

Explanation:

Returned results. For details, see Table 4.
Table 4 Response

Parameter

Type

Description

CommonMsg

ICommonMsg

Explanation:

Common information generated after an API call is complete, including the HTTP status code and error code. For details, see Table 5.

InterfaceResult

Table 6

Explanation:

Results outputted for a successful call. For details, see Table 6.

Restrictions:

This parameter is not included if the value of Status is greater than 300.
Table 5 ICommonMsg

Parameter

Type

Description

Status

number

Explanation:

HTTP status code returned by the OBS server.

Value range:

A status code is a group of digits indicating the status of a response. It ranges from 2xx (indicating successes) to 4xx or 5xx (indicating errors). For details, see Status Codes.

Code

string

Explanation:

Error code returned by the OBS server.

Message

string

Explanation:

Error description returned by the OBS server.

HostId

string

Explanation:

Request server ID returned by the OBS server.

RequestId

string

Explanation:

Request ID returned by the OBS server.

Id2

string

Explanation:

Request ID2 returned by the OBS server.

Indicator

string

Explanation:

Error code details returned by the OBS server.
Table 6 CompleteMultipartUploadOutput

Parameter

Type

Description

RequestId

string

Explanation:

Request ID returned by the OBS server

ETag

string

Explanation:

Base64-encoded, 128-bit MD5 value of an assembled object calculated based on the ETag of each part. The ETag is a unique identifier for the object's contents, used to determine if the object has been updated. For example, if the ETag value is A when an object is uploaded and becomes B when the object is downloaded, this indicates the contents of the object were changed. The ETag reflects changes of an object, not of the metadata. Objects created by the upload and copy operations have unique ETags after being encrypted using MD5.

Restrictions:

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

Bucket

string

Explanation:

Name of the bucket in which parts are assembled

Key

string

Explanation:

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

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Location

string

Explanation:

URL of the object obtained from assembling the parts.

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

VersionId

string

Explanation:

Version ID of the object obtained from assembling the parts. If versioning is enabled for the bucket, the object version ID will be returned.

SseKms

string

Explanation:

SSE-KMS is used for encrypting objects on the server side.

SseKmsKey

string

Explanation:

ID of the KMS master key when SSE-KMS is used.

SseC

string

Explanation:

SSE-C is used for encrypting objects on the server side.

SseCKeyMd5

string

Explanation:

MD5 value of the key used for encrypting objects when SSE-C is used. This value is used to check whether any error occurs during the transmission of the key.

Restrictions:

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

EncodingType

string

Explanation:

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

Value range:

url

Default value:

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

Code Examples

This example assembles the uploaded parts to complete multipart upload 00000188677110424014075CC4A77xxx of object example/objectname.

 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
 
// Import the OBS library.
// Use npm to install the client.
const ObsClient = require("esdk-obs-nodejs");
// Use the source code to install the client.
// var ObsClient = require('./lib/obs');

// Create an instance of ObsClient.
const obsClient = new ObsClient({
  // Obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways. Using hard coding may result in leakage.
  // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
  access_key_id: process.env.ACCESS_KEY_ID,
  secret_access_key: process.env.SECRET_ACCESS_KEY,
  // (Optional) If you use 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. You can obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways.
  // security_token: process.env.SECURITY_TOKEN,
  // Enter the endpoint corresponding to the region where the bucket is located. CN-Hong Kong is used here in this example. Replace it with the one currently in use.
  server: "https://obs.ap-southeast-1.myhuaweicloud.com"
});

async function completeMultipartUpload() {
  try {
    const params = {
      // Specify the bucket name.
      Bucket: "examplebucket",
      // Specify an object. example/objectname is used in this example.
      Key: "example/objectname",
      // Specify the multipart upload ID (00000188677110424014075CC4A77xxx in this example).
      UploadId: "00000188677110424014075CC4A77xxx",
// Specify the list of parts to be assembled. The parts must be sorted by part number in ascending order, and the parts can be inconsecutive.
      Parts: [
        { PartNumber: 1, ETag: "etag1" },
        { PartNumber: 2, ETag: "etag2" },
        { PartNumber: 3, ETag: "etag3" },
      ]
    };
    // Assemble parts.
    const result = await obsClient.completeMultipartUpload(params);
    if (result.CommonMsg.Status <= 300) {
      console.log("Complete multipart upload successful with bucket(%s) and object(%s)!", params.Bucket, params.Key);
      console.log("RequestId: %s", result.CommonMsg.RequestId);
      return;
    };
    console.log("An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    console.log("Status: %d", result.CommonMsg.Status);
    console.log("Code: %s", result.CommonMsg.Code);
    console.log("Message: %s", result.CommonMsg.Message);
    console.log("RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    console.log("An Exception was found, which means the client encountered an internal problem when attempting to communicate with OBS, for example, the client was unable to access the network.");
    console.log(error);
  };
};

completeMultipartUpload();