Initiating a multipart upload

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

You use the HTTP POST method with the uploads query parameter to initiate a multipart upload in a bucket.

To initiate a multipart upload, you must be an authenticated user. Additionally, you need write permission for the target bucket.

When you initiate a multipart upload, you specify a name for the object you're creating.

In initiate the multipart upload request, you can specify custom metadata to be added to the object when the multipart upload is completed. To do this, you use x-amz-meta- headers.

In the initiate multipart upload request, you can specify an ACL to be added to the object when the multipart upload is completed. To do this, you need to use ACL headers. You cannot use an ACL request body when initiating a multipart upload.

If the ACL you specify in a request to initiate a multipart upload is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not initiate the multipart upload.

You cannot change the custom metadata or ACL for a multipart object until the multipart upload used to create the object has been completed.

When you complete a multipart upload, you become the owner of the resulting object.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to initiate a multipart upload has either of these formats:

  • With the bucket name included in the hostname:
    POST /object-name?uploads HTTP/1.1
  • With the bucket name following the hostname:
    POST /bucket-name/object-name?uploads HTTP/1.1

The uploads query parameter is case sensitive.

Required headers

The list below describes the headers you can use in a request to initiate a multipart upload.

Authorization
Specifies user credentials or requests anonymous access.
Date
Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.
The date and time must always be specified using Greenwich Mean Time (GMT).
To specify the date and time, use this format:
DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
In this format:
DDD
The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
dd
The two-digit day of the month.
MMM
The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
yyyy
The four-digit year.
HH
The hour on a 24-hour clock.
mm
The number of minutes.
ss
The number of seconds.
For example:
Thu, 23 Mar 2017 14:27:05 +0000
All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.
Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the Date header above.

Optional headers

x-amz-acl
Adds a canned ACL to the bucket.
This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.
x-amz-grant-full-control
Grants full control over the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.
x-amz-grant-read
Grants the browse and read data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.
x-amz-grant-read-acp
Grants the read ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.
x-amz-grant-write
Grants the write and delete data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.
x-amz-grant-write-acp
Grants the write ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.
x-amz-meta-
Adds custom metadata to the resulting object when the multipart upload is completed.
x-amz-object-lock-mode
Specify the Object Lock mode status for an object. The value can be either GOVERNANCE or COMPLIANCE.
GOVERNANCE
Use for objects that are subject to retention policies that are governed by a regulatory body.
COMPLIANCE
Use for objects that are subject to strict regulatory requirements.
Example
x-amz-object-lock-mode: GOVERNANCE
x-amz-object-lock-retain-until-date
Specify the date and time until which an object must be retained. The date and time must be in YYYY-MM-DDTHH:MM:SSZ format, where YYYY represents the year, MM represents the month, DD represents the day, T represents the time separator, HH represents the hour in 24-hour format, MM represents the minute, SS represents the second and Z represents the time zone.
Example
x-amz-object-lock-retain-until-date: 2023-03-30T00:00:00Z
x-amz-object-lock-legal-hold
Specify the Legal hold status of an object version. Valid values are ON and OFF.
ON
You cannot overwrite or delete the object version until you remove the legal hold status.
OFF
You can overwrite or delete the object version.
Example
x-amz-object-lock-legal-hold: ON
x-hcp-pretty-print
Optionally, requests that the XML response body be formatted for readability. Valid values are:
true
Format the XML response body for readability.
false
Do not apply any special formatting to the XML response body.
The default is false.
The values true and false are not case sensitive.

Response headers

The list below describes the headers returned in response to a successful request to initiate a multipart upload.

Content-Type
Specifies the Internet media type of the response body. For a request to initiate a multipart upload, the value of this header is always application/xml;charset=UTF-8.
Date
The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:
DDD dd MMM yyyy HH:mm:ss GMT
For example:
Fri, 18 Sep 2020 14:27:05 GMT
Transfer-Encoding
Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always chunked.
x-amz-abort-date
Specifies the date and time when the multipart upload will be automatically aborted if it has not already been completed. The date and time are expressed in this format:
DDD, dd MMM yyyy hh:mm:ss GMT
For example:
Sat, 25 Mar 2017 17:19:26 GMT
x-amz-server-side-encryption
Specifies whether objects stored in HCP are encrypted. Possible values are:
  • If objects are encrypted, AES256
  • If objects are not encrypted, None
This header is returned only if the request headers include x-amz-server-side-encryption.

Response body

HCP returns information about the multipart upload that results from a successful initiate request in an XML response body.

The list below describes the XML elements in the response body returned in response to a request to initiate a multipart upload. The elements are listed in alphabetical order.

Bucket
Child of the InitiateMultipartUploadResult element.
The Bucket element specifies the name of the bucket where the multipart upload was initiated.
InitiateMultipartUploadResult
Root element.
Key
Child of the InitiateMultipartUploadResult element.
The Key element specifies the name of the object for which the multipart upload was initiated.
UploadId
Child of the InitiateMultipartUploadResult element.
The UploadId element specifies the upload ID for the multipart upload initiated by the request.
Use this ID in conjunction with the object name to identify the multipart upload in:
  • Requests to upload parts for the multipart upload
  • Requests to upload parts for the multipart upload by copying
  • Requests to complete the multipart upload
  • Requests to abort the multipart upload
  • Requests to list the parts that have been uploaded for the multipart upload
  • Responses to requests to list in-progress multipart uploads

Status codes

The table below describes HTTP status codes that can be returned in response to a request to initiate a multipart upload.

Code Meaning Description
200 OK HCP successfully initiated the multipart upload.
400 Bad Request

Possible reasons include:

  • The specified object name is too long.
  • An ACL grant header specifies an invalid grantee.
403 Forbidden

Possible reasons include:

  • The request specifies anonymous access. Only an authenticated user can initiate a multipart upload.
  • The credentials provided with the request are invalid.
  • You do not have permission to initiate multipart uploads in the specified bucket.
  • The specified bucket does not support multipart uploads.
  • The S3 compatible API is currently disabled for the specified bucket.
404 Not Found The specified bucket does not exist.
500 Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

501 Not Implemented The request includes the x-amz-acl header with an invalid value.
503 Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Initiating a multipart upload

Here’s a sample POST request that initiates a multipart upload for an object named acctg/RulesAndRegulations.pdf in the finance bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen --post -- -k
     "https://finance.europe.hcp.example.com/acctg/RulesAndRegulations.pdf?uploads"
     -H "x-hcp-pretty-print: true"

Request headers

POST /acctg/RulesAndRegulations.pdf?uploads HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:u0eqPDwPw1SR7kdZn87dnGACzaM=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
x-amz-server-side-encryption: None
x-amz-abort-date: Sat, 25 Mar 2017 17:19:26 GMT
Content-Type: application/xml;charset=UTF-8
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Bucket>finance</Bucket>
     <Key>acctg/RulesAndRegulations.pdf</Key>
     <UploadId>94837746087105</UploadId>
</InitiateMultipartUploadResult>