Initiating a Multipart Upload

Functions

Before using this operation, make an API operation call to create a multipart upload task. The system will return a globally unique upload ID as the multipart upload identifier. This identifier can be used in subsequent requests including UploadPart, CompleteMultipartUpload, and ListParts. Create a multipart upload task does not affect the object that has the same name as 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.

This operation supports server-side encryption.

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.

Request Syntax

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

Request Parameters

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

**Table 1** Request parameters
Parameter	Description	Mandatory
uploads	Indicates a multipart upload. Type: string NOTE: This parameter is an empty string. If this parameter is not contained in a request, the request performs a common upload using POST.	Yes
encoding-type	Encodes the Key in the response based on the specified type. If the Key contain control characters that are not supported by the XML 1.0 standard, you can set encoding-type to encode the Key in response. Type: string Value option: url	No

Request Headers

The request can use additional headers, as shown in Table 2.

**Table 2** Request headers
Header	Description	Mandatory
x-obs-acl	When initiating a multipart upload, you can add this message header to set the permission control policy for the object. The predefined common policies are as follows: private, public-read, and public-read-write. For details about each policy, see the ACL configuration using header fields in ACLs. Type: string Note: This header is a predefined policy expressed in a character string. Example: x-obs-acl: public-read-write	No
x-obs-grant-read	When initiating a multipart upload, you can use this header to grant all users in an account the permissions to read the object and obtain the object metadata. Type: string Example: x-obs-grant-read: ID=domainID. If multiple accounts are authorized, separate them with commas (,).	No
x-obs-grant-read-acp	When initiating a multipart upload, you can use this header to grant all users in an account the permission to obtain the object ACL. Type: string Example: x-obs-grant-read-acp: ID=domainID. If multiple accounts are authorized, separate them with commas (,).	No
x-obs-grant-write-acp	When initiating a multipart upload, you can use this header to grant all users in an account the permission to write the object ACL. Type: string Example: x-obs-grant-write-acp: ID=domainID. If multiple accounts are authorized, separate them with commas (,).	No
x-obs-grant-full-control	When initiating a multipart upload, you can use this header to grant all users in an account the permissions to read the object, obtain the object metadata and ACL, and write the object ACL. Type: string Example: x-obs-grant-full-control: ID=domainID. If multiple accounts are authorized, separate them with commas (,).	No
x-obs-storage-class	When initiating a multipart upload, you can add this header to specify the storage class for the object. If you do not use this header, the object storage class is the default storage class of the bucket. Type: string Storage class options: STANDARD (Standard), WARM (Infrequent Access), COLD (Archive), DEEP_ARCHIVE (Deep Archive). These values are case sensitive. Example: x-obs-storage-class: STANDARD	No
x-obs-persistent-headers	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. Type: string 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 merged, headers key1:value1 and key2:value2 will be returned, respectively, when you download the object and obtain 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 custom headers. The total length of this header and the custom metadata cannot exceed 8 KB. If the same keys are passed, values are separated with commas (,) and then returned in one 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?=. The values cannot contain spaces, equal signs (=), commas (,), semicolons (;), colons (:), or periods (.). If such characters are required, use URL or Base64 encoding.	No
x-obs-website-redirect-location	If a bucket is configured with the static website hosting function, it will redirect requests for this object to another object in the same bucket or to an external URL. OBS stores the value of this header in the object metadata. Type: string Default value: none Constraint: The value must be prefixed by a slash (/), http://, or https://. The length of the value cannot exceed 2 KB.	No
x-obs-server-side-encryption	Indicates that SSE-KMS is used. Type: string Example: x-obs-server-side-encryption: kms	No. This header is required when SSE-KMS is used.
x-obs-server-side-encryption-kms-key-id	Indicates the master key when SSE-KMS is used. If this header is not provided, the default master key will be used. If there is no such a default master key, OBS will create one and use it by default. Type: string The following two formats are supported: - regionID:domainID:key/key_id - key_id regionID indicates the ID of the region where the key belongs. domainID indicates the ID of the tenant where the key belongs. key_id indicates the ID of the key created in DEW. Examples: 1. x-obs-server-side-encryption-kms-key-id: region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 or 2. x-obs-server-side-encryption-kms-key-id: 4f1cd4de-ab64-4807-920a-47fc42e7f0d0	No
x-obs-server-side-encryption-customer-algorithm	Indicates the encryption algorithm when SSE-C is used. Type: string Example: x-obs-server-side-encryption-customer-algorithm: AES256 Constraint: This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5.	No. This header is required when SSE-C is used.
x-obs-server-side-encryption-customer-key	Indicates the key for encrypting objects when SSE-C is used. Type: string Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= Constraint: 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.	No. This header is required when SSE-C is used.
x-obs-server-side-encryption-customer-key-MD5	Indicates the MD5 value of the encryption key when SSE-C is used. The MD5 value is used to check whether any error occurs during the transmission of the key. Type: string Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Constraint: 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.	No. This header is required when SSE-C is used.
x-obs-expires	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). Type: integer Example: x-obs-expires:3	No
x-obs-object-lock-mode	WORM mode that will be applied to the object. Currently, only COMPLIANCE is supported. This header must be used together with x-obs-object-lock-retain-until-date. Type: string Example: x-obs-object-lock-mode:COMPLIANCE	No, but required when x-obs-object-lock-retain-until-date is present.
x-obs-object-lock-retain-until-date	Indicates the expiration time of the Object Lock retention. The value must be a UTC time that complies with ISO 8601, for example, 2015-07-01T04:11:15Z. This header must be used together with x-obs-object-lock-mode. Type: string Example: x-obs-object-lock-retain-until-date:2015-07-01T04:11:15Z	No, but required when x-obs-object-lock-mode is present.
x-obs-meta-*	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 user-defined metadata will be returned in the response when you retrieve the object or query the object metadata. For details, see User-Defined Object Metadata. Type: string Example: x-obs-meta-test: test metadata	No

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

Request Elements

This request involves no elements.

Response Syntax

    
         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

The response to the request uses common headers. For details, see Table 1.

**Table 3** Additional response headers
Header	Description
x-obs-server-side-encryption	This header is included in a response if SSE-KMS is used. Type: string Example: x-obs-server-side-encryption: kms
x-obs-server-side-encryption-kms-key-id	Indicates the master key ID. This header is included in a response when SSE-KMS is used. Type: string Format: regionID:domainID:key/key_id regionID indicates the ID of the region where the key belongs. domainID indicates the ID of the tenant where the key belongs. key_id indicates the key ID used in this encryption. Example: x-obs-server-side-encryption-kms-key-id: region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0
x-obs-server-side-encryption-customer-algorithm	Indicates the encryption algorithm. This header is included in a response when SSE-C is used. Type: string Example: x-obs-server-side-encryption-customer-algorithm: AES256
x-obs-server-side-encryption-customer-key-MD5	Indicates the MD5 value of a key used to encrypt objects. This header is included in a response if SSE-C is used. Type: string Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Response Elements

This response contains elements to indicate the upload ID and the key (name) of the object (bucket) for which the multipart upload was initiated. The returned information is used in the subsequent operations. Table 4 describes the elements.

**Table 4** Response elements
Element	Description
InitiateMultipartUploadResult	Container of a multipart upload task. Type: XML
Bucket	Indicates the name of the bucket to which the multipart upload was initiated. Type: string
Key	Indicates the object key in a multipart upload. Type: string
UploadId	Indicates the ID for the initiated multipart upload. This ID is used for the subsequent operation. Type: string
EncodingType	Encoding type of the key of an object that is uploaded in the multipart mode. If encoding-type is specified in the request, the Key in the response is encoded. Type: string

Error Responses

1. If the AK or signature is invalid, OBS returns 403 Forbidden and the error code is AccessDenied.

2. If the bucket is not found, OBS returns 404 Not Found and the error code is NoSuchBucket.

3. Check whether the user has the write permission for the specified bucket. If not, OBS returns 403 Forbidden and the error code is AccessDenied.

Other errors are included in Table 2.

Sample Request: Initiating a Multipart Upload

    
         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

    
         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)

    
         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)

    
         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>