startUpload method
Returns the ID that should be used in all subsequent operations for uploading objects.
If the object is to be stored with user-defined metadata, it should be passed in this request.
Request
POST /{bucket}/{key}?uploads HTTP/2
Path parameters
Parameter | Description |
---|---|
bucket |
Bucket name. |
key |
Object key. The object will be saved in Object Storage with the specified name. |
Query parameters
Parameter | Description |
---|---|
uploads |
Flag indicating the multipart upload operation. |
Headers
Use the necessary common request headers in requests.
You can also use the headers listed in the table below.
Header | Description |
---|---|
X-Amz-Meta-* |
Object user-defined metadata. Object Storage transforms all headers starting with X-Amz-Meta- as follows: X-Amz-Meta-foo-bar_baz → X-Amz-Meta-Foo-Bar_baz .Total user-defined header size must not exceed 2 KB. The size of user-defined data is determined as the length of the UTF-8 encoded string. The header names and their values are included when calculating the size. |
X-Amz-Storage-Class |
Object storage class. Possible values:
|
X-Amz-Object-Lock-Mode |
Type of retention put on the object (if the bucket is versioned and object lock is enabled in it):
On an object version, you can put only retention (the headers |
X-Amz-Object-Lock-Retain-Until-Date |
Date and time until which the object is retained, specified in any format described in the HTTP standardMon, 12 Dec 2022 09:00:00 GMT . Specified only together with the X-Amz-Object-Lock-Mode header. |
X-Amz-Object-Lock-Legal-Hold |
Type of legal hold put on the object (if the bucket is versioned and object lock is enabled in it):
On an object version, you can put only retention (the headers |
By using the headers listed below, you can set the ACL for an object to be uploaded.
Header | Description |
---|---|
X-Amz-Acl |
Sets a predefined ACL for an object. |
X-Amz-Grant-Read |
Grants the access grantee object read permission. |
X-Amz-Grant-Read-Acp |
Grants the access grantee object ACL read permission. |
X-Amz-Grant-Write-Acp |
Grants the access grantee object ACL write permission. |
X-Amz-Grant-Full-Control |
Grants the access grantee the following permissions: READ , WRITE , READ_ACP , and WRITE_ACP for an object. |
The value for an X-Amz-Grant-*
header is a comma-separated list of access grantees. Each access grantee is identified in a structure like <access_grantee_type>:<access_grantee_ID>
. Object Storage supports the following types of access grantees:
id
: access grantee is a cloud user.uri
: access grantee is a system group.
For example:
X-Amz-Grant-Read: uri="http://acs.amazonaws.com/groups/s3/AuthenticatedUsers"
Response
Headers
Responses can only contain common response headers.
Response codes
For a list of possible responses, see Responses.
A successful response contains additional data in XML format with the schema described below.
Data schema
<InitiateMultipartUploadResult>
<Bucket>bucket-name</Bucket>
<Key>object-key</Key>
<UploadId>upload-id</UploadId>
</InitiateMultipartUploadResult>
Tag | Description |
---|---|
InitiateMultipartUploadResult |
Response root tag. Path: /InitiateMultipartUploadResult . |
Bucket |
Name of the bucket the object is uploaded to. Path: /InitiateMultipartUploadResult/Bucket . |
Key |
Key associated with the object after the upload is complete. Path: /InitiateMultipartUploadResult/Key . |
uploadId |
Upload ID. All subsequent upload operations must pass this ID to Object Storage. Path: /InitiateMultipartUploadResult/UploadId . |