.. |br| raw:: html
.. _S3Features:
################
Общая информация
################
Объектное хранилище Облака КРОК поддерживает RESTful API, совместимый с AWS S3.
Для работы с Simple Storage Service API мы рекомендуем использовать `AWS CLI `_ или `S3cmd `_.
*********************
Поддерживаемые методы
*********************
Операции над бакетами
=====================
В таблице описаны методы API для работы с бакетами, доступные в AWS S3, и статус их поддержки Облаком КРОК.
.. list-table::
:widths: 18 11 11
:header-rows: 1
* - Функция
- Статус
- Комментарий
* - :ref:`S3APICreateBucket`
- Поддерживается
- :ref:`С ограничениями `
* - :ref:`S3DeleteBucket`
- Поддерживается
-
* - DeleteBucketAnalyticsConfiguration
- Не поддерживается
-
* - :ref:`S3DeleteBucketCors`
- Поддерживается
-
* - DeleteBucketEncryption
- Поддерживается
- :ref:`С ограничениями `
* - DeleteBucketInventoryConfiguration
- Не поддерживается
-
* - :ref:`S3DeleteBucketLifecycleConfiguration`
- Поддерживается
-
* - DeleteBucketMetricsConfiguration
- Не поддерживается
-
* - DeleteBucketOwnershipControls
- Не поддерживается
-
* - :ref:`S3DeleteBucketPolicy`
- Поддерживается
-
* - DeleteBucketReplication
- Не поддерживается
-
* - :ref:`S3DeleteBucketWebsite`
- Поддерживается
-
* - DeletePublicAccessBlock
- Не поддерживается
-
* - GetBucketAccelerateConfiguration
- Не поддерживается
-
* - :ref:`S3GetBucketAcl`
- Поддерживается
-
* - GetBucketAnalyticsConfiguration
- Не поддерживается
-
* - :ref:`S3GetBucketCors`
- Поддерживается
-
* - GetBucketEncryption
- Поддерживается
- :ref:`С ограничениями `
* - GetBucketInventoryConfiguration
- Не поддерживается
-
* - :ref:`S3GetBucketLifecycleConfiguration`
- Поддерживается
-
* - GetBucketLocation
- Поддерживается
- :ref:`С ограничениями `
* - GetBucketLogging
- Не поддерживается
-
* - GetBucketMetricsConfiguration
- Не поддерживается
-
* - GetBucketNotificationConfiguration
- Не поддерживается
-
* - GetBucketOwnershipControls
- Не поддерживается
-
* - :ref:`S3GetBucketPolicy`
- Поддерживается
-
* - S3GetBucketPolicyStatus
- Не поддерживается
-
* - GetBucketReplication
- Не поддерживается
-
* - GetBucketRequestPayment
- Поддерживается
- :ref:`С ограничениями `
* - GetBucketTagging
- Не поддерживается
-
* - :ref:`S3GetBucketVersioning`
- Поддерживается
-
* - :ref:`S3GetBucketWebsite`
- Поддерживается
-
* - GetPublicAccessBlock
- Не поддерживается
-
* - GetObjectLockConfiguration
- Не поддерживается
-
* - :ref:`S3HeadBucket`
- Поддерживается
-
* - :ref:`S3ListBuckets`
- Поддерживается
-
* - ListBucketAnalyticsConfigurations
- Не поддерживается
-
* - ListBucketInventoryConfigurations
- Не поддерживается
-
* - ListBucketmetricsConfigurations
- Не поддерживается
-
* - :ref:`S3ListMultipartUploads`
- Поддерживается
-
* - ListObjects
- Поддерживается
-
* - :ref:`S3ListObjectsV2`
- Поддерживается
-
* - :ref:`S3ListObjectVersions`
- Поддерживается
-
* - PutBucketAccelerateConfiguration
- Не поддерживается
-
* - :ref:`S3PutBucketAcl`
- Поддерживается
-
* - PutBucketAnalyticsConfiguration
- Не поддерживается
-
* - :ref:`S3PutBucketCors`
- Поддерживается
-
* - PutBucketEncryption
- Поддерживается
- :ref:`С ограничениями `
* - PutBucketInventoryConfiguration
- Не поддерживается
-
* - :ref:`S3PutBucketLifecycleConfiguration`
- Поддерживается
- :ref:`С ограничениями `
* - PutBucketLogging
- Не поддерживается
-
* - PutBucketMetricsConfiguration
- Не поддерживается
-
* - PutBucketNotificationConfiguration
- Не поддерживается
-
* - PutBucketOwnershipControls
- Не поддерживается
-
* - :ref:`S3PutBucketPolicy`
- Поддерживается
- :ref:`С ограничениями `
* - PutBucketReplication
- Не поддерживается
-
* - PutBucketRequestPayment
- Поддерживается
- :ref:`С ограничениями `
* - PutBucketTagging
- Не поддерживается
-
* - :ref:`S3PutBucketVersioning`
- Поддерживается
-
* - :ref:`S3PutBucketWebsite`
- Поддерживается
-
* - PutObjectLockConfiguration
- Не поддерживается
-
* - PutPublicAccessBlock
- Не поддерживается
-
Операции над объектами
======================
В таблице описаны методы API для работы с объектами, доступные в AWS S3, и статус их поддержки Облаком КРОК.
.. list-table::
:widths: 18 11 11
:header-rows: 1
* - Функция
- Статус
- Комментарий
* - :ref:`S3AbortMultipartUpload`
- Поддерживается
-
* - :ref:`S3CompleteMultipartUpload`
- Поддерживается
-
* - :ref:`S3CreateMultipartUpload`
- Поддерживается
-
* - :ref:`S3CopyObject`
- Поддерживается
-
* - :ref:`S3DeleteObject`
- Поддерживается
-
* - :ref:`S3DeleteObjects`
- Поддерживается
-
* - :ref:`S3DeleteObjectTagging`
- Поддерживается
-
* - :ref:`S3GetObject`
- Поддерживается
-
* - :ref:`S3GetObjectAcl`
- Поддерживается
-
* - GetObjectLegalHold
- Не поддерживается
-
* - GetObjectRetention
- Не поддерживается
-
* - :ref:`S3GetObjectTagging`
- Поддерживается
-
* - GetObjectTorrent
- Не поддерживается
-
* - :ref:`S3HeadObject`
- Поддерживается
-
* - :ref:`S3ListParts`
- Поддерживается
-
* - PostObject
- Поддерживается
-
* - :ref:`S3PutObject`
- Поддерживается
- :ref:`С ограничениями `
* - :ref:`S3PutObjectAcl`
- Поддерживается
-
* - PutObjectLegalHold
- Не поддерживается
-
* - PutObjectRetention
- Не поддерживается
-
* - :ref:`S3PutObjectTagging`
- Поддерживается
- :ref:`С ограничениями `
* - RestoreObject
- Не поддерживается
-
* - SelectObjectContent
- Не поддерживается
-
* - :ref:`S3UploadPart`
- Поддерживается
-
* - S3UploadPartCopy
- Поддерживается
-
Ограничения на поддерживаемые методы
====================================
.. _restrictions_Server_Side_encryption_ru:
Ограничения Server Side Encryption
----------------------------------
В рамках AWS S3 поддерживаются две спецификации Server Side Encryption (SSE):
- SSE-KMS
- SSE-C
Облако КРОК поддерживает только спецификацию SSE-C (см. :ref:`пример шифрования объекта с её использованием `).
Методы ``Get/Put/DeleteBucketEncryption`` относятся к спецификации SSE-KMS, которая не поддерживается.
Формально методы работают, но воспользоваться шифрованием бакета по спецификации SSE-KMS вы пока не сможете.
.. _restrictions_Bucket_Location_ru:
Ограничения Bucket Location
---------------------------
Установка Location с помощью параметра *LocationConstraint* не поддерживается.
Метод ``GetBucketLocation`` всегда возвращает ``null``.
.. _restrictions_Bucket_requestPayment_ru:
Ограничения Bucket Request Payment
----------------------------------
Данный подход не поддерживается.
Формально методы ``Get/PutBucketRequestPayment`` работают, но воспользоваться этой возможностью вы пока не сможете.
.. _restrictions_Bucket_lifecycle_ru:
Ограничения Bucket Lifecycle
----------------------------
Поддерживаются правила для удаления объектов и версий объектов.
Не поддерживаются правила перемещения объектов между классами хранения (Storage Classes).
.. _restrictions_Bucket_policy_ru:
Ограничения Bucket Policy
-------------------------
Теги объектов не поддерживаются в Bucket Policy.
Поддерживаемые действия (Actions):
- s3:AbortMultipartUpload
- s3:CreateBucket
- s3:DeleteBucketPolicy
- s3:DeleteBucket
- s3:DeleteBucketWebsite
- s3:DeleteObject
- s3:DeleteObjectVersion
- s3:GetBucketAcl
- s3:GetBucketCORS
- s3:GetBucketLocation
- s3:GetBucketPolicy
- s3:GetBucketRequestPayment
- s3:GetBucketVersioning
- s3:GetBucketWebsite
- s3:GetLifecycleConfiguration
- s3:GetObjectAcl
- s3:GetObject
- s3:GetObjectVersion
- s3:ListAllMyBuckets
- s3:ListMultipartUploadParts
- s3:ListBuckets
- s3:ListBucketVersions
- s3:ListBucketMultipartUploads
- s3:ListMultipartUploadParts
- s3:PutBucketAcl
- s3:PutBucketCORS
- s3:PutBucketPolicy
- s3:PutBucketRequestPayment
- s3:PutBucketVersioning
- s3:PutBucketWebsite
- s3:PutLifecycleConfiguration
- s3:PutObjectAcl
- s3:PutObject
- s3:PutObjectVersionAcl
В качестве Principal в Bucket Policy пока можно использовать только "*".
В рамках Bucket Policy поддерживаются следующие условия (Condition Keys) для всех запросов:
- aws:CurrentTime
- aws:EpochTime
- aws:PrincipalType
- aws:Referer
- aws:SecureTransport
- aws:SourceIp
- aws:UserAgent
- aws:username
Условия (condition keys) для запросов, относящихся к бакетам.
.. list-table::
:widths: 27 27
:header-rows: 1
* - Действие (Action)
- Условие (Condition Key)
* - s3:createBucket
- s3:x-amz-acl |br|
s3:x-amz-grant-, где одно из разрешений read/write/read-acp/write-acp/full-control
* - s3:ListBuckets |br|
s3:ListBucketVersions
- s3:prefix |br|
s3:delimiter |br|
s3:max-keys
* - s3:PutBucketAcl
- s3:x-amz-acl |br|
s3:x-amz-grant-, где одно из разрешений read/write/read-acp/write-acp/full-control
Условия (condition keys) для запросов, относящихся к объектам.
.. list-table::
:widths: 27 27
:header-rows: 1
* - Действие (Action)
- Условие (Condition Key)
* - s3:PutObject
- s3:x-amz-acl |br|
s3:x-amz-grant-, где одно из разрешений read/write/read-acp/write-acp/full-control |br|
s3:x-amz-copy-source |br|
s3:x-amz-metadata-directive |br|
* - s3:PutObjectAcl |br|
s3:PutObjectVersionAcl
- s3:x-amz-acl |br|
s3-amz-grant-, где одно из разрешений read/write/read-acp/write-acp/full-control
.. _restrictions_Object_tagging_ru:
Ограничения Object Tagging
--------------------------
Использование тегов объектов не поддерживается в Bucket Policy, а также в Bucket Lifecycle.
*****************
Общий вид запроса
*****************
Вид конкретного запроса зависит от выполняемой операции и передаваемых параметров.
Большинство запросов содержит :ref:`типовые заголовки `, в частности аутентифицированные запросы должны включать заголовок `Authorization`.
Если запросы выполняются напрямую из кода, то тогда вам необходимо самостоятельно :ref:`сгенерировать подпись для заголовка `.
Примерный вид запроса
=====================
::
{GET|HEAD|PUT|DELETE} /<бакет>/<ключ объекта>?<список параметров> HTTP/1.1
Host: storage.cloud.croc.ru
X-Amz-Content-Sha256:
X-Amz-Date: <Дата в формате ISO08601>
Authorization: <Параметры авторизации в соответствии с AWS Signature Version 4>
<Тело запроса>
Имя бакета и хоста
==================
Доступ к бакету может осуществляться двумя способами.
Первый (предпочтительный) метод идентифицирует бакет как имя хоста (virtual bucket host name).
::
GET / HTTP/1.1
Host: mybucket.storage.cloud.croc.ru
Второй (унаследованный) метод идентифицирует бакет как каталог высшего уровня URI.
::
GET /mybucket HTTP/1.1
Host: storage.cloud.croc.ru
*****************
Типовые заголовки
*****************
.. _S3APIHeaders:
Типовые заголовки запроса
=========================
Данные заголовки используются в большинстве запросов.
.. list-table::
:widths: 10 15
:header-rows: 1
* - Заголовок запроса
- Описание
* - Authorization
- Токен авторизации
* - Content-Length
- Длина тела запроса
* - Content-Type
- MIME-тип тела запроса
* - Date
- Время и дата запроса (UTC)
* - Host
- Имя хост-сервера
* - x-amz-content-sha256
- Хеш SHA256 для тела запроса (при аутентификации с помощью AWS Signature Version 4)
Типовые заголовки ответа
========================
Данные заголовки присутствуют в большинстве ответов.
.. list-table::
:widths: 10 15
:header-rows: 1
* - Заголовок запроса
- Описание
* - Content-Length
- Длина тела ответа в байтах
* - Content-Type
- MIME-тип тела запроса, например Application/XML
* - Date
- Дата и время ответа в формате UTC
* - x-amz-request-id
- Идентификатор запроса
**************
Статусы ответа
**************
При успешном выполнении запроса возвращаются коды 2xx, при невыполнении и ошибке — коды 4xx и 500.
.. list-table::
:widths: 10 10
:header-rows: 1
* - HTTP-статус
- Код ответа
* - 100
- Continue
* - 200
- Success
* - 201
- Created
* - 202
- Accepted
* - 204
- NoContent
* - 206
- Partial content
* - 304
- NotModified
* - 400
- BadDigest
* - 400
- EntityTooLarge
* - 400
- InvalidArgument
* - 400
- InvalidBucketName
* - 400
- InvalidDigest
* - 400
- InvalidObjectName
* - 400
- InvalidPart
* - 400
- InvalidPartOrder
* - 400
- RequestTimeout
* - 400
- UnresolvableGrantByEmailAddress
* - 403
- AccessDenied
* - 403
- QuotaExceeded
* - 403
- RequestTimeTooSkewed
* - 403
- UserSuspended
* - 404
- NoSuchBucket
* - 404
- NoSuchKey
* - 404
- NoSuchUpload
* - 405
- MethodNotAllowed
* - 408
- RequestTimeout
* - 409
- BucketAlreadyExists
* - 409
- BucketNotEmpty
* - 411
- MissingContentLength
* - 412
- PreconditionFailed
* - 416
- InvalidRange
* - 422
- UnprocessableEntity
* - 500
- InternalError