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.
For more information on getting started with the API and the general request format, see How to use the S3 API.
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 appropriate common headers in your request.
You can also use the headers listed in the table below.
| Header | Description |
|---|---|
X-Amz-Meta-* |
User-defined object metadata. Object Storage converts all headers starting with X-Amz-Meta- according to the following rule: X-Amz-Meta-foo-bar_baz → X-Amz-Meta-Foo-Bar_baz.The total size of user-defined headers 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. It may have any of the following 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):
For an object version, you can use only retention ( |
X-Amz-Object-Lock-Retain-Until-Date |
Date and time of end of retention in any format described in the HTTP standard, e.g., Mon, 12 Dec 2022 09:00:00 GMT. Specify it only 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):
For an object version, you can use only retention ( |
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 READ, WRITE, READ_ACP, and WRITE_ACP permissions for the object. |
The value for the X-Amz-Grant-* headers is a comma-separated list of access grantees. Each access grantee is identified in a structure <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 public group.
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 to upload the file 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 provide this ID to Object Storage.> Path: /InitiateMultipartUploadResult/UploadId. |