######
Bucket
######

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

.. _S3APICreateBucket:

************
CreateBucket
************

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

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

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

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

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

.. dropdown:: Запрос
   :open:

   ::

     PUT /bucket1 HTTP/1.1
     Host: storage.cloud.croc.ru
     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

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

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

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

.. dropdown:: Ответ

   ::

     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

.. _S3HeadBucket:

**********
HeadBucket
**********

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

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

.. dropdown:: Запрос
   :open:

   ::

     HEAD /bucket1 HTTP/1.1
     Host: storage.cloud.croc.ru
     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

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

.. dropdown:: Ответ

   ::

     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

.. _S3ListBuckets:

***********
ListBuckets
***********

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

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

.. dropdown:: Запрос
   :open:

   ::

    GET / HTTP/1.1
    Host: storage.cloud.croc.ru
    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

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

.. dropdown:: Ответ

   ::

     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>

.. _S3PutBucketVersioning:

*******************
PutBucketVersioning
*******************

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

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

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

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

.. dropdown:: Запрос
   :open:

   ::

     PUT /bucket1/?versioning=null HTTP/1.1
     Host: storage.cloud.croc.ru
     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>

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

.. dropdown:: Ответ

   ::

     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

.. _S3GetBucketVersioning:

*******************
GetBucketVersioning
*******************

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

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

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

.. dropdown:: Запрос
   :open:

   ::

     GET /bucket1/?versioning=null HTTP/1.1
     Host: storage.cloud.croc.ru
     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

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

.. dropdown:: Ответ

   ::

     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>

.. _S3ListObjectsV2:

*************
ListObjectsV2
*************

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

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

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

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

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

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

.. dropdown:: Запрос
   :open:

   ::

     GET /bucket1/?list-type=2&delimiter=/ HTTP/1.1
     Host: storage.cloud.croc.ru
     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

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

.. dropdown:: Ответ

   ::

     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>

.. _S3ListObjectVersions:

******************
ListObjectVersions
******************

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

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

.. dropdown:: Запрос
   :open:

   ::

     GET /bucket1/?versions=null HTTP/1.1
     Host: storage.cloud.croc.ru
     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

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

.. dropdown:: Ответ

   ::

     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>

.. _S3DeleteBucket:

************
DeleteBucket
************

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

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

.. dropdown:: Запрос
   :open:

   ::

     DELETE /bucket1 HTTP/1.1
     Host: storage.cloud.croc.ru
     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

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

.. dropdown:: Ответ

   ::

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