Help Center/ Object Storage Service/ SDK Reference/ BrowserJS/ Object APIs/ Basic Operations/ Multipart Upload/ Initiating a Multipart Upload
Updated on 2026-08-14 GMT+08:00
View PDF
Share

Initiating a Multipart Upload

Function

This API is used to initiate a multipart upload and obtain a globally unique upload ID. You can use this upload ID in your subsequent requests including abortMultipartUpload, listMultipartUploads, and listParts.

If you have any questions during development, post them on the Issues page of GitHub. For details about parameters and usage of each API, see the API Reference.

Restrictions

  • To initiate a multipart upload, you must be the bucket owner or have the required permission (obs:object:PutObject granted using IAM or PutObject granted using a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
  • The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
  • After initiating a multipart upload and uploading one or more parts, you must complete or abort the multipart upload. Otherwise, fragments will occupy your storage space and incur storage fees.

You can also call the API for resumable upload (encapsulation and enhancement of multipart upload) provided by the SDK to implement multipart 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 properties comply with those set in the first creation request.

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.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

ACL

String

No

Explanation:

ACL that can be pre-defined when a bucket is created. For details about ACLs, see ACLs.

Value range:

private: Private read and write. A bucket or an object can only be accessed by its owner.

public-read: Public read and private write. Anyone can obtain the object content and metadata.

public-read-write: Public read and write. Anyone can obtain the object content and metadata. This permission works the same as public-read.

bucket-owner-full-control: Only the bucket and object owners have 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 permission to the bucket owner, the bucket owner can have full control over your object.

Default value:

None

GrantRead

String

No

Explanation:

When creating an object, you can use this header to grant all users of a tenant the permissions to read the object and obtain the object metadata.

Example: id=domainID

Restrictions:

Use commas (,) to separate multiple tenants.

Value range:

The value must be a valid ID. For details about how to obtain the ID, see Obtaining Account, IAM User, Project, User Group, Region, and Agency Information.

Default value:

None

GrantReadAcp

String

No

Explanation:

When creating an object, you can use this header to grant all users of a tenant the permission to obtain the object ACL.

Example: id=domainID

Restrictions:

Use commas (,) to separate multiple tenants.

Value range:

The value must be a valid ID. For details about how to obtain the ID, see Obtaining Account, IAM User, Project, User Group, Region, and Agency Information.

Default value:

None

GrantWriteAcp

String

No

Explanation:

When creating an object, you can use this header to grant all users in a domain the permission to write the object ACL.

Example: id=domainID

Restrictions:

Use commas (,) to separate multiple tenants.

Value range:

The value must be a valid ID. For details about how to obtain the ID, see Obtaining Account, IAM User, Project, User Group, Region, and Agency Information.

Default value:

None

GrantFullControl

String

No

Explanation:

When creating an object, you can use this header to grant all users of a tenant the permissions to read the object and obtain the object metadata.

Example: id=domainID

Restrictions:

Use commas (,) to separate multiple tenants.

Value range:

The value must be a valid ID. For details about how to obtain the ID, see Obtaining Account, IAM User, Project, User Group, Region, and Agency Information.

Default value:

None

StorageClass

String

No

Explanation:

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

Value range:

STANDARD: Standard storage

WARM: Infrequent Access storage

COLD: Archive storage

DEEP_ARCHIVE: Deep Archive storage

Default value:

None

Metadata

dict

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.

Default value:

None

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 another object in the 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.

Restrictions:

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

Default value:

None

Expires

Number

No

Explanation:

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

Restrictions:

This parameter can only be configured when uploading an object.

Value range:

An integer greater than or equal to 0, in days

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.

Value range:

See What Is Content-Type (MIME)?

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.

CacheControl

String

No

Explanation:

Cache-Control header in the response. It specifies the cache behavior of the web page when an object is downloaded.

Default value:

None

ContentDisposition

String

No

Explanation:

Default file name for the requested object. When the object is downloaded or accessed, the object appears in the browser or download dialog box with this default file name.

Default value:

None

ContentLanguage

String

No

Explanation:

Language or language combination for visitors to customize and use. For details, see the definition of ContentLanguage in the HTTP protocol.

Default value:

None

ContentEncoding

String

No

Explanation:

Content-Encoding header in the response. It specifies which encoding format is applied to the object.

Default value:

None

SseMode

String

No

Explanation:

Encryption method

Value range:

kms: SSE-KMS is used for encryption.

AES256: SSE-OBS and the AES256 algorithm are used for encryption.

Default value:

None

SseAlgorithm

String

No

Explanation:

Encryption algorithm

Value range:

If this header is not included, the AES256 algorithm is used.

SM4: The SM4 algorithm is used.

Default value:

None

SseKmsKey

String

No

Explanation:

ID of the KMS master key used in SSE-KMS mode

Value range:

Valid value formats are as follows:

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

In the preceding formats:

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.

SseKmsProjectId

String

No

Explanation:

ID of the project (not an enterprise project) where the KMS CMK belongs when SSE-KMS is used

Value range:

Project ID that matches the key specified in SseKmsKey

Default value:

None

SseC

String

No

Explanation:

Algorithm used for SSE-C

Value range:

AES256: SSE-C and the AES-256 algorithm are used.

Default value:

None

SseCKey

String

No

Explanation:

Custom key used in SSE-C encryption. The value is a Base64-encoded 256-bit key.

Default value:

None

SseCKeyMd5

String

No

Explanation:

Base64-encoded MD5 value of the key

Default value:

None

EncodingType

String

No

Explanation:

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

Value range:

url

Default value:

None. If you do not configure this parameter, encoding is not applied.

Responses

Table 2 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 3 InterfaceResult

Parameter

Type

Description

UploadId

str

Explanation:

Multipart upload ID, for example, 000001648453845DBB78F2340DD460D8

Value range:

The value must contain 1 to 32 characters.

Default value:

None

Sample Code

You can call ObsClient.initiateMultipartUpload to initiate a multipart upload.

// Create an ObsClient instance.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK before storing them in the configuration file or environment variables. In this example, the AK and SK are stored in environment variables. Before running the code in this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // 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.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 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'
});

obsClient.initiateMultipartUpload({
       Bucket : 'bucketname',
       Key : 'objectname',
       ContentType : 'text/plain',
       Metadata : {'property' : 'property-value'}
}, function (err, result) {
       if(err){
              console.error('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                     console.log('UploadId-->' + result.InterfaceResult.UploadId);
              }
       }
});
  • When initiating a multipart upload, you can use the ContentType and Metadata parameters to respectively set the MIME type and custom metadata of an object.
  • 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.
Parent topic: Multipart Upload