Bucket#

Основные операции с бакетами.

CreateBucket#

Создаёт новый бакет.

Запрос на создание бакета должен быть аутентифицирован. Иначе говоря, создать бакет могут только аутентифицированные пользователи. Отправитель запроса становится владельцем бакета.

При создании бакета можно сразу задать права доступа к бакету для проектов и групп. Подробнее о правах доступа и способах их задания можно прочитать в разделе ACL.

Пример запроса#

Создаёт бакет с именем bucket1 и предоставляет права доступа на чтение для анонимных пользователей и права доступа на запись для пользователей (проектов) с указанными адресом электронной почты и ID.

Запрос
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

Пример ответа#

Если имя бакета удовлетворяет требованиям, вызов будет выполнен успешно. Если имя бакета уже занято и пользователь не является владельцем бакета, то в выполнении запроса будет отказано.

Если бакет с данным именем уже существует, но пользователь является его владельцем, то операция завершится успешно. При этом если в заголовке были заданы, например, параметры ACL, то они не будут изменены.

Ответ
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

Пример запроса (включение блокировки бакета)#

Создаёт бакет, для которого можно включить защиту версий объектов от удаления и перезаписи (см. подробнее). При создании бакета с включённым Object Lock автоматически включается версионирование, которое нельзя отключить.

Запрос
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

Пример ответа#

Ответ
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#

Проверяет наличие бакета. Если бакет существует, то в заголовках ответа возвращается информация о бакете — количество содержащихся в нём объектов и занимаемый ими объём.

Пример запроса#

Запрос
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

Пример ответа#

Ответ
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#

Возвращает список всех бакетов, созданных пользователем, который инициировал запрос.

Пример запроса#

Запрос
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

Пример ответа#

Ответ
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#

Включает/приостанавливает версионирование бакета.

Только владелец бакета может изменить состояние версионирования. Версионирование можно включить, но нельзя отключить — только приостановить. Соответственно, версионирование можно перевести в одно из двух состояний:

  • Enabled — включает контроль версий в бакете. Все добавляемые объекты получают уникальный идентификатор версии.

  • Suspended — приостанавливает версионирование объектов в бакете. Все добавляемые объекты автоматически получают версию null.

Пример запроса#

Запрос
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>

Пример ответа#

Ответ
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#

Возвращает статус версионирования.

Если в бакете версионирование не было включено, он не имеет статуса версионирования. В этом случае запрос не возвращает значения статуса.

Пример запроса#

Запрос
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

Пример ответа#

Ответ
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#

Возвращает список объектов в бакете.

В К2 Облаке поддерживаются обе версии метода — ListObject и ListObjectV2. Мы рекомендуем использовать версию ListObjectV2 как более новую. При вызове в качестве параметра запроса необходимо указать list-type=2.

В одном запросе может быть выведено максимум 1000 объектов. Если в запросе были выведены не все объекты, для продолжения их вывода в следующем запросе необходимо указать содержащийся в ответе Continuation Token.

Вы можете использовать такие параметры запроса как delimiter, prefix и start-after для фильтрации выводимых объектов.

Пример запроса#

В запросе указан разделитель /, поэтому для объектов, в которых он имеется, выводится только общий префикс.

Запрос
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

Пример ответа#

Ответ
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#

Возвращает список версий всех объектов в бакете. Вы можете использовать параметры запроса для фильтрации выводимых версий.

Пример запроса#

Запрос
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

Пример ответа#

Ответ
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#

Удаляет бакет. Удалить можно только бакет, не содержащий объектов и их версий. После удаления имя бакета становится доступно для повторного использования.

Пример запроса#

Запрос
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

Пример ответа#

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