Help Center/ Object Storage Service/ API Reference/ Object APIs/ Operations on Multipart Upload/ Initiating a Multipart Upload
Updated on 2026-05-26 GMT+08:00
View PDF
Share

Initiating a Multipart Upload

Function

This API is used to create a multipart upload task. The system will return a globally unique upload ID as the multipart upload identifier. You can use this ID to upload, assemble, and list parts. Creating a multipart upload task does not affect the object that has the same name as the object to be uploaded in multiple parts. You can create more than one multipart upload tasks for an object. This operation request can contain headers x-obs-acl, x-obs-meta-*, Content-Type, and Content-Encoding. The headers are recorded in the multipart upload metadata.

WORM

If a bucket has WORM enabled, you can configure object-level retention policies when initiating multipart uploads. You can specify the x-obs-object-lock-mode and x-obs-object-lock-retain-until-date headers when you initiate a multipart upload to protect the object assembled. If you do not specify these two headers but have configured a default bucket-level WORM policy, this default policy automatically applies to the object newly assembled. You can also configure or update a WORM retention policy after the object is assembled.

Different from uploads with PUT and POST, a multipart upload only requires that the date specified in the x-obs-object-lock-retain-until-date header be no later than the initiation time, but does not have to be later than the completion time of the multipart upload. When the default bucket-level WORM policy is applied, the protection starts when the object parts are assembled and ends once the default bucket-level protection period expires. Before assembling the object parts uploaded, the multipart upload can be canceled and will not be affected by the WORM configuration.

Authorization

To call this API, you must be the bucket owner or have the permission to initiate a multipart upload. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

  • If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
    • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you must have the obs:object:PutObject permission. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you must have the obs:object:putObject permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

      Action

      Access Level

      Resource Type (*: Required)

      Condition Key

      Alias

      Dependencies

      obs:object:putObject

      Permission_management

      object *

      g:EnterpriseProjectId

      -
      • kms:cmk:create
      • kms:cmk:list
      • kms:cmk:createDataKey

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
      • obs:x-obs-acl
  • If you use bucket policies for authorization, you must have the obs:object:putObject permission. For details, see Creating a Custom Bucket Policy.

URI

POST /{object_key}

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

Request Syntax

1
2
3
4
 
POST /ObjectName?uploads  HTTP/1.1  
Host: bucketname.obs.region.myhuaweicloud.com 
Date: date
Authorization: authorization

URI Parameters

This request uses parameters to specify a multipart upload. Table 1 describes the parameters.

Table 1 URI parameters

Parameter

Type

Mandatory

Description

uploads

String

Yes

Definition

Indicates a multipart upload.

Constraints

  • This parameter is an empty string.
  • If this parameter is not included, the request is treated as an ordinary POST upload.

Range

An empty string.

Default Value

N/A

encoding-type

String

No

Definition

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.

Constraints

N/A

Range

URL

Default Value

N/A. If you do not specify this parameter, encoding is not applied.

Request Headers

This request uses common headers. For details, see Table 3.

The request can use additional headers shown in Table 2.

Table 2 Request headers

Header

Type

Mandatory

Description

x-obs-acl

String

No

Definition

When initiating a multipart upload, you can add this header to set an object ACL.

Example: x-obs-acl: public-read-write

Constraints

Use character strings.

Range

  • private
  • public-read
  • public-read-write

For details about each policy, see "Configuring an ACL Using Header Fields" in ACLs.

Default Value

private

x-obs-grant-read

String

No

Definition

When initiating a multipart upload, you can use this header to grant all users in a domain the permissions to read the object and obtain the object metadata.

Example: x-obs-grant-read: ID=domainID.

Constraints

Use commas (,) to separate multiple domains.

Range

N/A

Default Value

N/A

x-obs-grant-read-acp

String

No

Definition

When initiating a multipart upload, you can use this header to grant all users in a domain the permissions to obtain the object ACL.

Example: x-obs-grant-read-acp: ID=domainID.

Constraints

Use commas (,) to separate multiple domains.

Range

N/A

Default Value

N/A

x-obs-grant-write-acp

String

No

Definition

When initiating a multipart upload, you can use this header to grant all users in a domain the permissions to write the object ACL.

Example: x-obs-grant-write-acp: ID=domainID

Constraints

Use commas (,) to separate multiple domains.

Range

N/A

Default Value

N/A

x-obs-grant-full-control

String

No

Definition

When initiating a multipart upload, you can use this header to grant all users in a domain the following permissions:

Permissions to read objects, obtain object metadata, obtain object ACLs, and write object ACLs.

Example: x-obs-grant-full-control: ID=domainID.

Constraints

Use commas (,) to separate multiple domains.

Range

N/A

Default Value

N/A

x-obs-storage-class

String

No

Definition

When initiating a multipart upload, you can add this header to specify the storage class for the object.

Example: x-obs-storage-class: STANDARD

Constraints

  • If you do not use this header, the object storage class is the default storage class of the bucket.
  • The value is case-sensitive.

Range

  • STANDARD
  • WARM
  • COLD
  • DEEP_ARCHIVE

Default Value

By default, the storage class of the bucket is inherited.

x-obs-persistent-headers

String

No

Definition

When initiating a multipart upload, you can add the x-obs-persistent-headers header in an HTTP request to specify one or more user-defined response headers. After all parts in the multipart upload are merged, user-defined response headers will be returned in the response header when you retrieve the object or query the object metadata.

Constraints

  • Response headers customized in this way cannot be prefixed with x-obs-. For example, you should use key1 instead of x-obs-key1.
  • Standard HTTP headers, such as host, content-md5, origin, range, and Content-Disposition, cannot be specified as user-defined headers.
  • The total length of this header and the custom metadata cannot exceed 8 KB.
  • If multiple values are passed for the same key, they are separated by commas (,) and returned all at once for that key.
  • If the decoded value contains non-US-ASCII or unrecognizable characters, the server processes the value as a string and encapsulates it using ?UTF-8?B?<(str)>?=, but does not decode the value. For instance, value key1:abbc will be returned as key1:=?UTF-8?B?abbc?= in the response.
  • The values cannot contain spaces, equal signs (=), commas (,), semicolons (;), colons (:), or periods (.). If such characters are required, use URL or Base64 encoding.
  • Format: x-obs-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2)...

    Note: Items, such as key1 and key2, are user-defined headers. If they contain non-ASCII or unrecognizable characters, they can be encoded using URL or Base64. The server processes these headers as character strings, but does not decode them. Items, such as value1 and value2 are the values of the corresponding headers. base64_encode indicates that the value is encoded using Base64. A user-defined header and its Base64-encoded value are connected using a colon (:) to form a key-value pair. All key-value pairs are separated with a comma (,) and are placed in the x-obs-persistent-headers header. The server then decodes the uploaded value.

    Example: x-obs-persistent-headers: key1:dmFsdWUx,key2:dmFsdWU

    After all parts in the multipart upload are assembled, headers key1:value1 and key2:value2 will be returned, respectively, when you download the object and obtain the object metadata.

Range

N/A

Default Value

N/A

x-obs-website-redirect-location

String

No

Definition

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.

To another object in the same bucket:

x-obs-website-redirect-location:/anotherPage.html

To an external URL:

x-obs-website-redirect-location:http://www.example.com/

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

Constraints

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

Default Value

N/A

x-obs-server-side-encryption

String

No. This header is required when SSE-KMS is used.

Definition

Indicates that SSE-KMS is used.

Example: x-obs-server-side-encryption: kms

Constraints

N/A

Range

  • kms: SSE-KMS is used for encryption.
  • AES256: SSE-OBS and the AES256 algorithm are used.

Default Value

N/A

x-obs-server-side-encryption-kms-key-id

String

No

Definition

ID of a specified key used for SSE-KMS encryption. For details about how to obtain a key ID, see Viewing a Key.

Constraints

This header can only be used when you specify kms for the x-obs-server-side-encryption header.

Default Value

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is no default master key, OBS will create one and use it.

x-obs-server-side-encryption-bucket-key-enabled

String

No

Definition

Whether to enable the SSE-KMS bucket key feature.

Constraints

If you set this header to true, you must also specify x-obs-server-side-encryption-kms-key-id to specify the key ID.

Range

  • true: The bucket key is enabled.
  • false: The bucket key is disabled.

Default Value

false

x-obs-server-side-encryption-customer-algorithm

String

No. This header is required when SSE-C is used.

Definition

The algorithm used for encryption.

Example: x-obs-server-side-encryption-customer-algorithm: AES256

Constraints

  • This header is used only when SSE-C is used.
  • This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5.

Range

AES256

Default Value

N/A

x-obs-server-side-encryption-customer-key

String

No. This header is required when SSE-C is used.

Definition

The key used for encrypting an object.

Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

Constraints

  • This header is used only when SSE-C is used.
  • This header is a Base64-encoded 256-bit key and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key-MD5.

Range

N/A

Default Value

N/A

x-obs-server-side-encryption-customer-key-MD5

String

No. This header is required when SSE-C is used.

Definition

The MD5 value of the encryption key. The MD5 value is used to check whether any error occurs during the transmission of the key.

Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraints

  • This header is used only when SSE-C is used.
  • This header is a Base64-encoded 128-bit MD5 value and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key.

Range

Base64-encoded MD5 value of the key ID.

Default Value

N/A

x-obs-expires

Integer

No

Definition

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted. (The calculation starts from when the object was last modified).

Example: x-obs-expires:3

Constraints

This parameter can be configured only when uploading the object. It cannot be modified by calling a metadata modification API.

Range

An integer greater than or equal to 0, in days

Default Value

N/A

x-obs-tagging

String

No

Definition

An object's tag information in key-value pairs. Multiple tags can be added at the same time.

Example: x-obs-tagging:TagA=A&TagB&TagC

Constraints

  • If a tag key or value contains special characters, equal signs (=), or full-width characters, it must be URL-encoded.
  • If there is no equal sign (=) in a configuration, the tag value is considered left blank.

Range

N/A

Default Value

N/A

x-obs-object-lock-mode

String

No, but required when x-obs-object-lock-retain-until-date is present.

Definition

WORM mode to be applied to an object.

Example: x-obs-object-lock-mode:COMPLIANCE

Constraints

This parameter must be used together with x-obs-object-lock-retain-until-date.

Range

Only COMPLIANCE (compliance mode) is supported.

Default Value

N/A

x-obs-object-lock-retain-until-date

String

No, but required when x-obs-object-lock-mode is present.

Definition

When the WORM policy of the object expires.

Example: x-obs-object-lock-retain-until-date:2015-07-01T04:11:15.297Z

Constraints

  • The value must be a UTC time that complies with the ISO 8601 standard. Example: 2015-07-01T04:11:15.297Z
  • This parameter must be used together with x-obs-object-lock-mode.

Range

The time must be later than the current time.

Default Value

N/A

x-obs-meta-*

String

No

Definition

When initiating a multipart upload, you can use a header starting with x-obs-meta- in the HTTP request to define object metadata for easy management. The custom metadata will be returned in the response when you retrieve the object or query the object metadata. For details, see Managing Object Metadata.

Example: x-obs-meta-test: test metadata

Constraints

This parameter can only be passed in HTTP request headers and cannot exceed 8 KB.

Range

N/A

Default Value

N/A

For details about other common message headers, see Table 3.

Request Body

This request contains no request body parameters.

Response Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
HTTP/1.1 status_code
Date: date
Content-Length: length
Connection: status

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<InitiateMultipartUploadResult xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
    <Bucket>BucketName</Bucket>  
    <Key>ObjectName</Key>  
    <UploadId>uploadID</UploadId> 
</InitiateMultipartUploadResult>

Response Headers

This response uses common headers. For details, see Table 1.

Table 3 Response headers

Header

Type

Description

x-obs-server-side-encryption

String

Definition

The encryption method used by the server.

Example: x-obs-server-side-encryption: kms

Constraints

This header is included in a response if SSE-KMS is used.

Range

  • kms: SSE-KMS is used for encryption.
  • AES256: SSE-OBS and the AES256 algorithm are used.

Default Value

N/A

x-obs-server-side-encryption-kms-key-id

String

Definition

ID of a specified key used for SSE-KMS encryption. For details about how to obtain a key ID, see Viewing a Key.

Constraints

This header can only be used when you specify kms for the x-obs-server-side-encryption header.

Default Value

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is no default master key, OBS will create one and use it.

x-obs-sse-kms-key-project-id

String

Definition

If SSE-KMS encryption is used with a custom master key, the ID of the project (not enterprise project) to which the custom master key belongs is returned.

Range

ID of the project (not enterprise project) to which the custom master key specified by x-obs-server-side-encryption-kms-key-id belongs

x-obs-server-side-encryption-customer-algorithm

String

Definition

The algorithm used for encryption.

Example: x-obs-server-side-encryption-customer-algorithm: AES256

Constraints

This header is included in a response if SSE-C is used for server-side encryption.

Range

AES256

Default Value

N/A

x-obs-server-side-encryption-customer-key-MD5

String

Definition

The MD5 value of the encryption key.

Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraints

This header is included in a response if SSE-C is used for server-side encryption.

Range

Base64-encoded MD5 value of the key ID.

Default Value

N/A

Response Body

This response contains elements that indicate the multipart upload ID and the bucket and object names, which are used for uploading and assembling parts. Table 4 describes the elements.

Table 4 Response body parameters

Element

Type

Description

InitiateMultipartUploadResult

XML

Definition

Container of a multipart upload task.

Constraints

N/A

Range

N/A

Default Value

N/A

Bucket

String

Definition

Indicates the bucket name in the multipart upload.

Constraints

  • 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 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.

Range

N/A

Default Value

N/A

Key

String

Definition

Name of the object in the multipart upload. 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 access path is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Constraints

See Object Overview.

Range

The value must contain 1 to 1,024 characters.

Default Value

N/A

UploadId

String

Definition

ID of the multipart upload, which is used to specify a multipart upload in uploading parts

Constraints

N/A

Range

The value must contain 1 to 32 characters.

Default Value

N/A

EncodingType

String

Definition

Encoding type for the name of an object in a multipart upload. If encoding-type is specified in the request, the Key in the response is encoded.

Constraints

N/A

Range

URL

Default Value

N/A. If you do not specify this parameter, encoding is not applied.

Error Responses

  1. If the AK or signature was invalid, OBS returns 403 Forbidden and the error code is AccessDenied.
  2. If the bucket was not found, OBS returns 404 Not Found and the error code is NoSuchBucket.
  3. If the user did not have the write permission for the specified bucket, OBS returns 403 Forbidden and the error code is AccessDenied.

Other errors are included in Table 2.

Sample Request: Initiating a Multipart Upload

1
2
3
4
 
POST /objectkey?uploads  HTTP/1.1 
Host: examplebucket.obs.region.myhuaweicloud.com
Date: WED, 01 Jul 2015 05:14:52 GMT 
Authorization: OBS AKIAIOSFODNN7EXAMPLE:VGhpcyBtZXNzYWdlIHNpZ25lZGGieSRlbHZpbmc=

Sample Response: Initiating a Multipart Upload

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 
HTTP/1.1 200 OK 
Server: OBS
x-obs-id-2: Weag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg== 
x-obs-request-id: 996c76696e6727732072657175657374 
Date: WED, 01 Jul 2015 05:14:52 GMT
Content-Length: 303

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<InitiateMultipartUploadResult xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
  <Bucket>bucketname</Bucket>  
  <Key>objectkey</Key>  
  <UploadId>DCD2FC98B4F70000013DF578ACA318E7</UploadId> 
</InitiateMultipartUploadResult>

Sample Request: Initiating a Multipart Upload (with the ACL Configured)

1
2
3
4
5
 
POST /objectkey?uploads  HTTP/1.1 
Host: examplebucket.obs.region.myhuaweicloud.com
Date: WED, 01 Jul 2015 05:15:43 GMT
x-obs-grant-write-acp:ID=52f24s3593as5730ea4f722483579ai7,ID=a93fcas852f24s3596ea8366794f7224
Authorization: OBS AKIAIOSFODNN7EXAMPLE:VGhpcyBtZXNzYWdlIHNpZ25lZGGieSRlbHZpbmc=

Sample Response: Initiating a Multipart Upload (with the ACL Configured)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 
HTTP/1.1 200 OK 
Server: OBS
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCTnv+daB51p+IVhAvWN7s5rSKhcWqDFs 
x-obs-request-id: BB78000001648457112DF37FDFADD7AD 
Date: WED, 01 Jul 2015 05:15:43 GMT
Content-Length: 303

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<InitiateMultipartUploadResult xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
  <Bucket>bucketname</Bucket>  
  <Key>objectkey</Key>  
  <UploadId>000001648453845DBB78F2340DD460D8</UploadId> 
</InitiateMultipartUploadResult>
Parent Topic: Operations on Multipart Upload