Bucket#

Basic operations with a bucket.

CreateBucket#

Creates a new bucket.

The request to create a bucket must be authenticated. In other words, only authenticated users can create a bucket. The request sender becomes the bucket owner.

When creating a bucket, you can immediately set the access rights to the bucket for projects and groups. To learn more about access rules and how to set them, see the ACL section.

Sample Request#

Creates a bucket named bucket1 and grants read access to anonymous users and write access to users (projects) with the specified email address and ID.

Request
PUT /bucket1 HTTP/1.1
Host: s3.k2.cloud
x-amz-grant-read: uri="http://acs.amazonaws.com/groups/global/AllUsers"
x-amz-grant-write: id="37c6ca16-be63-5839-afe0-660c0a45ed1c", emailAddress="user@company"
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220527T132429Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220527/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-grant-read, Signature=8a09d0ffbb8a1f431f2cc22a528f628aff5eca740c67d1e4b41f139437c6dd48

Sample Response#

If the bucket name meets the requirements, the request will be successful. If the bucket name is already in use and the user is not the bucket owner, then the request will be denied.

If a bucket with the desired name already exists, but the user owns it, then the response status will be successful. However, if, for example, ACL parameters were specified in the header, they will not be changed.

Response
HTTP/1.1 200 OK
x-amz-request-id: tx000000000000001391795-006290d111-41e6f988-default
content-length: 0
date: Fri, 27 May 2022 13:24:33 GMT

Request example (enabling bucket locking)#

The request creates a bucket for which object version protection can be enabled to prevent deletion and overwriting (for details, see). When a bucket is created with Object Lock enabled, versioning is automatically enabled and cannot be disabled.

Request
PUT /bucket1 HTTP/1.1
Host: s3.k2.cloud
X-Amz-Bucket-Object-Lock-Enabled: True
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20240805T082933Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220527/{region}/s3/aws4_request, SignedHeaders=host;x-amz-bucket-object-lock-enabled;x-amz-content-sha256;x-amz-date, Signature=a0c259d0a074e63188aef13f91b56d47d663d57ba9b280ac6851c9e3330caf50

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx00000197b929f19c01abf-0066b08e12-b929c455-default
content-length: 0
date: Fri, Mon, 05 Aug 2024 08:32:18 GMT

HeadBucket#

Checks whether the bucket exists. If the bucket exists, then the response headers include information about the bucket: the object count and overall data volume in the bucket.

Sample Request#

Request
HEAD /bucket1 HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220530T074551Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220530/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=c9da58fad9755d07a4c1f201d4bea83912a793060ea3fa06140d18a1edf177cf

Sample Response#

Response
HTTP/1.1 200 OK
x-rgw-object-count: 8
x-rgw-bytes-used: 44308
x-amz-request-id: tx0000000000000057e1ada-006294762f-41e7b39b-default
content-length: 0
date: Mon, 30 May 2022 07:45:51 GMT

ListBuckets#

Returns a list of buckets created by the user who initiated the request.

Sample Request#

Request
GET / HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220527T140745Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220527/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=129c98cce689142130a813afa8b0f5c2cce91e0ab6d39730e70192f0fd1e1f54

Sample Response#

Response
HTTP/1.1 200 OK
transfer-encoding: chunked
x-amz-request-id: tx00000000000000235b496-006290db34-4017b271-default
content-type: application/xml
date: Fri, 27 May 2022 14:07:48 GMT

<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
        <DisplayName>user@company</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>bucket1</Name>
            <CreationDate>2022-05-20T14:30:59.773Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>bucket2</Name>
            <CreationDate>2022-05-20T14:48:10.035Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

PutBucketVersioning#

Enables/suspends bucket versioning.

Only the bucket owner can change the versioning status. Versioning can be enabled but not disabled — only paused. Accordingly, you can switch versioning into one of two statuses:

  • Enabled — Turns on versioning for the objects in the bucket, All objects added to the bucket receive unique version IDs.

  • Suspended — Suspends versioning for the objects in the bucket. All objects added to the bucket receive the null version ID.

Sample Request#

Request
PUT /bucket1/?versioning=null HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: beaead3198f7da1e70d03ab969765e0821b24fc913697e929e726aeaebf0eba3
X-Amz-Date: 20220530T093435Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220530/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=ca822abe600f255231340b6d25a80077d233237c31898f19c3b58d72073bc823
Content-Type: text/plain
Content-Length: 131

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Status>Enabled</Status>
</VersioningConfiguration>

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx000000000000005912e15-0062948faa-41e7b39b-default
content-type: application/xml
content-length: 0
date: Mon, 30 May 2022 09:34:34 GMT

GetBucketVersioning#

Returns the versioning status.

If versioning was not enabled for the bucket, then it does not have a versioning status. In this case, the response will not include the status value.

Sample Request#

Request
GET /bucket1/?versioning=null HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220530T094109Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220530/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=4e8593eff552c8acf5a92bfd860a998e1fe3553328ae0303cb26a2a14411aa7f

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx0000000000000058f110f-0062949135-4017b271-default
content-type: application/xml
content-length: 192
date: Mon, 30 May 2022 09:41:09 GMT

<?xml version="1.0" encoding="UTF-8"?>
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Status>Enabled</Status>
    <MfaDelete>Disabled</MfaDelete>
</VersioningConfiguration>

ListObjectsV2#

Returns a list of objects in the bucket.

K2 Cloud supports both action versions: ListObject and ListObjectV2. We recommend using ListObjectV2, which is newer. In request, specify list-type=2 as a parameter.

One request can return max. 1,000 objects. If not all objects were returned in the response, then to list other objects specify the Continuation Token in the next request. The Continuation Token can be found in the response.

You can use request parameters, such as delimiter, prefix, and start-after to filter output objects.

Sample Request#

The / separator is specified in the request, so only the common prefix is output for objects that contain it.

Request
GET /bucket1/?list-type=2&delimiter=/ HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220527T163922Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220527/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=0ce8b8fd2d4e2cc338a08abe270dafdfd7aac6c548e44865ec8eae4c9aa08a9b

Sample Response#

Response
HTTP/1.1 200 OK
transfer-encoding: chunked
x-amz-request-id: tx000000000000002534a89-006290febe-41e7b39b-default
content-type: application/xml
date: Fri, 27 May 2022 16:39:26 GMT

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>bucket</Name>
    <Prefix></Prefix>
    <MaxKeys>1000</MaxKeys>
    <Delimiter>/</Delimiter>
    <IsTruncated>false</IsTruncated>
    <CommonPrefixes>
        <Prefix>docs/</Prefix>
    </CommonPrefixes>
    <CommonPrefixes>
        <Prefix>photos/</Prefix>
    </CommonPrefixes>
    <Contents>
        <Key>picture.gif</Key>
        <LastModified>2022-04-20T13:18:20.347Z</LastModified>
        <ETag>&quot;b181be800d7561f6d9fe3d3c3d75f85d&quot;</ETag>
        <Size>478617</Size>
        <StorageClass>STANDARD</StorageClass>
        <Type>Normal</Type>
    </Contents>
    <Contents>
        <Key>index1.html</Key>
        <LastModified>2021-01-24T09:34:13.597Z</LastModified>
        <ETag>&quot;7d38cbaf941c5da9d9ad73d88c214098&quot;</ETag>
        <Size>181</Size>
        <StorageClass>STANDARD</StorageClass>
        <Type>Normal</Type>
    </Contents>
    <KeyCount>5</KeyCount>
</ListBucketResult>

ListObjectVersions#

Returns a list of versions of all objects in the bucket. You can use the request parameters to filter output versions.

Sample Request#

Request
GET /bucket1/?versions=null HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220530T081531Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220530/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=87e68374f3d1f5b858274559869132a438b884a2ba3bc1aaa116166832e1ea51

Sample Response#

Response
HTTP/1.1 200 OK
transfer-encoding: chunked
x-amz-request-id: tx0000000000000030aab8a-00629497fe-41e6f988-default
content-type: application/xml
date: Mon, 30 May 2022 10:10:06 GMT

<?xml version="1.0" encoding="UTF-8"?>
<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>bucket1</Name>
    <Prefix></Prefix>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <KeyMarker></KeyMarker>
    <VersionIdMarker></VersionIdMarker>
    <Version>
        <Key>document1.docx</Key>
        <VersionId>cqMsFC2R1-dFAmodV.AKMkB92imKWQg</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2022-05-17T15:15:51.444Z</LastModified>
        <ETag>&quot;396b7f346217de1446d8cc3f712adcba&quot;</ETag>
        <Size>243</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
            <DisplayName>user@company</DisplayName>
        </Owner>
        <Type>Normal</Type>
    </Version>
    <Version>
        <Key>document2.docx</Key>
        <VersionId>qdisORivbaUanXFdCj45oIFyvZ1iWfc</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2022-05-17T15:10:54.204Z</LastModified>
        <ETag>&quot;35afa54b0f1922171c5daec1672e708d&quot;</ETag>
        <Size>644</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
            <DisplayName>user@company</DisplayName>
        </Owner>
        <Type>Normal</Type>
    </Version>
</ListVersionsResult>

DeleteBucket#

Deletes a bucket. The bucket can be deleted only if it does not contain objects or their versions. Once the bucket is deleted, its name is available for reuse.

Sample Request#

Request
DELETE /bucket1 HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220527T143047Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220527/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=991bff92e01f8764cb222daea65504b85150ad456bd45909952f3f8cd0a72472

Sample Response#

Response
HTTP/1.1 204 No Content
x-amz-request-id: tx00000000000000141fd5a-006290e09b-415d5bdc-default
date: Fri, 27 May 2022 14:30:51 GMT