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

Initiating a Multipart Upload (SDK for Node.js)

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

Function

This API initiates a multipart upload and returns a globally unique upload ID. You can use this upload ID in your subsequent requests for uploading, assembling, and listing parts. Initiating multipart upload tasks do not affect existing objects with the same names as the involved objects in those tasks. There can be more than one multipart upload for the same object. Each multipart upload initiation request can contain additional headers such as contentType, contentEncoding, and the headers for ACL and custom metadata. These headers are recorded in the multipart upload metadata. After the API for initiating a multipart upload is successfully called, an upload ID will be returned. This ID will be used in subsequent operations.

Restrictions

  • To initiate a multipart upload, 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 was initiated and one or more parts have been uploaded, you will be charged for storing these parts until you complete or cancel the upload.

Method

ObsClient.initiateMultipartUpload(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.eu-west-101.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

ACL

AclType

No

Explanation:

An access control list (ACL) that can be pre-defined when creating a bucket. For details about ACLs, see ACLs.

Restrictions:

None

Value range:

See Table 2.

Default value:

private

WebsiteRedirectLocation

string

No

Explanation:

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

The request is redirected to object anotherPage.html in the same bucket:

WebsiteRedirectLocation:/anotherPage.html

The request is redirected to an external URL:

WebsiteRedirectLocation:http://www.example.com/

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

Value range:

None

Restrictions:

  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.

Default value:

None

ContentType

string

No

Explanation:

MIME type of the file to be uploaded. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

Restrictions:

None

Value range:

See What Is Content-Type (MIME)? (SDK for Node.js)

Default value:

If you do not specify this parameter when uploading an object, the SDK determines the object type based on the suffix of the specified object name and automatically assigns a value to this parameter.

StorageClass

StorageClassType

No

Explanation:

Object storage class. If this parameter is not specified, the object inherits the storage class of its bucket.

Restrictions:

None

Value range:

See Table 3.

Default value:

STANDARD

Metadata

object

No

Explanation:

Custom metadata of the object to be uploaded. You can add a header starting with x-obs-meta- in the request to define metadata. The custom metadata will be returned in the response when you retrieve the object or query the object metadata.

Restrictions:

  • The custom metadata cannot exceed 8 KB in total. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case insensitive, but are stored in lowercase in OBS. The key values are case sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.

Value range:

None

Default value:

None

GrantRead

string

No

Explanation:

ID (domain_id) of an account the READ permission is granted to. The account with the READ permission can read the current object and obtain its metadata.

Restrictions:

If multiple accounts are authorized, separate them with commas (,).

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js)

Default value:

None

GrantReadAcp

string

No

Explanation:

ID (domain_id) of an account the READ_ACP permission is granted to. The account with the READ_ACP permission can read the ACL of the current object.

Restrictions:

If multiple accounts are authorized, separate them with commas (,).

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js)

Default value:

None

GrantWriteAcp

string

No

Explanation:

ID (domain_id) of an account the WRITE_ACP permission is granted to. The account with the WRITE_ACP permission can modify the ACL of the current object.

Restrictions:

If multiple accounts are authorized, separate them with commas (,).

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js)

Default value:

None

GrantFullControl

string

No

Explanation:

ID (domain_id) of an account the FULL_CONTROL permission is granted to. The account with the FULL_CONTROL permission can read the current object, obtain its metadata, and obtain and modify its ACL.

Restrictions:

If multiple accounts are authorized, separate them with commas (,).

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js)

Default value:

None

Expires

number

No

Explanation:

Expiration time of the object (calculated from the latest modification time of the object). Expired objects are automatically deleted.

Restrictions:

  • The value cannot be smaller than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you cannot specify a value less than 10.
  • This parameter can only be configured when uploading an object.

Value range:

1 to (263 - 1), in days

Default value:

None

SseKms

string

Yes when SSE-KMS is used

Explanation:

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

Restrictions:

Currently, only KMS is supported.

Value range:

kms

Default value:

None

SseKmsKey

string

No

Explanation:

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

Restrictions:

Valid value formats are as follows:

  1. regionID:domainID:key/key_id
  2. key_id

In the preceding formats:

Value range:

None

Default value:

  • If this parameter is not specified, the default master key will be used.
  • If there is not a default master key, OBS will create one and use it.

SseC

string

Yes when SSE-C is used

Explanation:

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

Restrictions:

Only AES256 is supported.

Value range:

AES256

Default value:

None

SseCKey

string

Yes when SSE-C is used

Explanation:

Key used for encrypting the object when SSE-C is used

Restrictions:

A Base64-encoded, 256-bit value, for example, K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

Value range:

None

Default value:

None

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 AclType

Constant

Default Value

Description

ObsClient.enums.AclPrivate

private

Private read and write

A bucket or object can only be accessed by its owner.

ObsClient.enums.AclPublicRead

public-read

Public read and private write

If this permission is granted on a bucket, anyone can read the object list, multipart uploads, metadata, and object versions in the bucket.

If this permission is granted on an object, everyone can obtain the content and metadata of the object.

ObsClient.enums.AclPublicReadWrite

public-read-write

Public read and write

If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart upload tasks.

If this permission is granted on an object, everyone can obtain the content and metadata of the object.

ObsClient.enums.AclPublicReadDelivered

public-read-delivered

Public read on a bucket as well as the objects in the bucket.

If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions and read the content and metadata of objects in the bucket.

NOTE:

AclPublicReadDelivered does not apply to objects.

ObsClient.enums.AclPublicReadWriteDelivered

public-read-write-delivered

Public read and write on a bucket as well as the objects in the bucket.

If this permission is granted on a bucket, anyone can read the object list, multipart uploads, metadata, and object versions in the bucket and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of objects in the bucket.

NOTE:

AclPublicReadWriteDelivered does not apply to objects.

ObsClient.enums.AclBucketOwnerFullControl

bucket-owner-full-control

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this policy to the bucket owner, the bucket owner can have full control over your object. For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets the bucket-owner-full-control policy for object x, user B then has the control over object x.
Table 3 StorageClassType

Constant

Default Value

Description

ObsClient.enums.StorageClassStandard

STANDARD

Standard storage class.

Features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

ObsClient.enums.StorageClassWarm

WARM

Infrequent Access storage class.

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but becomes instantly available when needed.

ObsClient.enums.StorageClassCold

COLD

Archive storage class.

Used for storing rarely accessed (once a year) data.

Responses

Table 4 Responses

Type

Description

Table 5

NOTE:

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

Explanation:

Returned results. For details, see Table 5.
Table 5 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 6.

InterfaceResult

Table 7

Explanation:

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

Restrictions:

This parameter is not included if the value of Status is greater than 300.
Table 6 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 7 InitiateMultipartUploadOutput

Parameter

Type

Description

RequestId

string

Explanation:

Request ID returned by the OBS server

Bucket

string

Explanation:

Name of the bucket involved in the multipart upload.

Key

string

Explanation:

Object name in the multipart upload. 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.eu-west-101.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

UploadId

string

Explanation:

Multipart upload ID, for example, 000001648453845DBB78F2340DD460D8.

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 initiates a multipart upload for 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
 
// 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/eu/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. EU-Dublin is used here in this example. Replace it with the one currently in use.
  server: "https://obs.eu-west-101.myhuaweicloud.eu"
});

async function initiateMultipartUpload() {
  try {
    const params = {
      // Specify the bucket name.
      Bucket: "examplebucket",
      // Specify the object (example/objectname in this example).
      Key: "example/objectname",
    };
    // Initiate the multipart upload.
    const result = await obsClient.initiateMultipartUpload(params);
    if (result.CommonMsg.Status <= 300) {
      console.log("Initiate multipart upload successfull with bucket(%s) and object(%s)!", params.Bucket, params.Key);
      console.log("RequestId: %s", result.CommonMsg.RequestId);
     // A globally unique identifier of the multipart upload task, which will be used in uploading and assembling parts.
      console.log("UploadId: %s", result.InterfaceResult.UploadId);
      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);
  };
};

initiateMultipartUpload();

Helpful Links