Initiate Multipart Upload

Before using multipart upload APIs, send an Initiate Multipart Upload request. The system will return a globally unique upload ID as the multipart upload identifier. This identifier can be used in follow-up requests including Upload Part, Complete Multipart Upload, and List Parts. Initiate Multipart Upload does not affect the object that has the same name as the multipart upload. You can create more than one multipart upload for an object. An Initiate Multipart Upload request can contain headers x-amz-acl, x-amz-meta-*, Content-Type, and Content-Encoding. The headers are recorded in the multipart upload metadata.

This operation supports server-side encryption.

Request Syntax

POST /ObjectName?uploads  HTTP/1.1 
Host: bucketname.obs.cn-north-1.myhwclouds.com
 
Date: date
Authorization: authorization

Request Parameters

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

Table 1 Request parameter

Parameter

Description

Required or Optional

uploads

Indicates the ID of the multipart upload to be initiated.

Type: string

Required

Request Headers

This request uses common headers. For details about common request headers, see Table 1.

This request also uses additional headers, as described in Table 2.

Table 2 Request headers

Header

Description

Required or Optional

x-amz-website-redirect-location

If a bucket is configured as a website, redirects 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: none

Constraint: The value must be prefixed by a slash (/), http://, or https://. The length of the value cannot exceed 2 KB.

Optional

x-amz-server-side-encryption

Indicates that SSE-KMS is used.

Type: string

Example: x-amz-server-side-encryption:aws:kms

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

x-amz-server-side-encryption-aws-kms-key-id

Indicates the master key ID. This header is used in SSE-KMS mode. If the customer does not provide the master key, the default master key will be used.

Type: string

Example: x-amz-server-side-encryption-aws-kms-key-id:arn:aws:kms:sichuan:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

Optional

x-amz-server-side-encryption-customer-algorithm

Indicates an encryption algorithm. The header is used in SSE-C mode.

Type: string

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

Constraints: This header must be used together with x-amz-server-side-encryption-customer-key and x-amz-server-side-encryption-customer-key-MD5.

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

x-amz-server-side-encryption-customer-key

Indicates a key used to encrypt objects. The header is used in SSE-C mode.

Type: string

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

Constraints: This header is a base64-encoded 256-bit key and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5.

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

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

Indicates the MD5 value of a key used to encrypt objects. The header is used in SSE-C mode. The MD5 value is used to check whether any error occurs during the transmission of the key.

Type: string

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

Constraints: This header is a base64-encoded 128-bit MD5 value and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key.

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

For details about common request headers, see Common Request Headers.

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.cn-north-1.myhwclouds.com/doc/2015-06-30/">
    <Bucket>BucketName</Bucket> 
    <Key>ObjectName</Key> 
    <UploadId>uploadID</UploadId>
</InitiateMultipartUploadResult> 

Response Headers

This response uses common headers. For details about common response headers, see Common Response Headers.

Table 3 Response headers

Header

Description

x-amz-server-side-encryption

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

Type: string

Example: x-amz-server-side-encryption:aws:kms

x-amz-server-side-encryption-aws-kms-key-id

Indicates the master key ID. This header is included in a response if SSE-KMS is used.

Example: x-amz-server-side-encryption-aws-kms-key-id:arn:aws:kms:sichuan:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

x-amz-server-side-encryption-customer-algorithm

Indicates an encryption algorithm. This header is included in a response if SSE-C is used.

Type: string

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

x-amz-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-amz-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 Upload Part and Complete Multipart Upload operations. Table 4 describes the elements.

Table 4 Response elements

Element

Description

InitiateMultipartUploadResult

Indicates the container for the response.

Type: XML

Bucket

Indicates the name of the bucket to which the multipart upload was initiated.

Type: string

Key

Indicates the key of the object for which the multipart upload was initiated.

Type: string

UploadId

Indicates the ID for the initiated multipart upload. This ID is used for the subsequent Upload Part operation.

Type: string

Error Responses

  • If an AK or signature is invalid, OBS returns status code 403 Forbidden and error code AccessDenied.
  • If the requested bucket does not exist, OBS returns status code 404 Not Found and error code NoSuchBucket.
  • If the requester does not have the WRITE permission for the requested bucket, OBS returns status code 403 Forbidden and error code AccessDenied.

For details about other error responses, see Table 1.

Registration