Общая информация#

Объектное хранилище К2 Облака поддерживает RESTful API, совместимый с AWS S3. Для работы с Simple Storage Service API мы рекомендуем использовать AWS CLI или S3cmd.

Поддерживаемые методы#

Операции над бакетами#

В таблице описаны методы API для работы с бакетами, доступные в AWS S3, и статус их поддержки К2 Облаком.

Функция

Статус

Комментарий

CreateBucket

Поддерживается

С ограничениями

DeleteBucket

Поддерживается

DeleteBucketAnalyticsConfiguration

Не поддерживается

DeleteBucketCors

Поддерживается

DeleteBucketEncryption

Поддерживается

С ограничениями

DeleteBucketInventoryConfiguration

Не поддерживается

DeleteBucketLifecycleConfiguration

Поддерживается

DeleteBucketMetricsConfiguration

Не поддерживается

DeleteBucketOwnershipControls

Не поддерживается

DeleteBucketPolicy

Поддерживается

DeleteBucketReplication

Не поддерживается

DeleteBucketWebsite

Поддерживается

DeletePublicAccessBlock

Не поддерживается

GetBucketAccelerateConfiguration

Не поддерживается

GetBucketAcl

Поддерживается

GetBucketAnalyticsConfiguration

Не поддерживается

GetBucketCors

Поддерживается

GetBucketEncryption

Поддерживается

С ограничениями

GetBucketInventoryConfiguration

Не поддерживается

GetBucketLifecycleConfiguration

Поддерживается

GetBucketLocation

Поддерживается

С ограничениями

GetBucketLogging

Не поддерживается

GetBucketMetricsConfiguration

Не поддерживается

GetBucketNotificationConfiguration

Не поддерживается

GetBucketOwnershipControls

Не поддерживается

GetBucketPolicy

Поддерживается

S3GetBucketPolicyStatus

Не поддерживается

GetBucketReplication

Не поддерживается

GetBucketRequestPayment

Поддерживается

С ограничениями

GetBucketTagging

Не поддерживается

GetBucketVersioning

Поддерживается

GetBucketWebsite

Поддерживается

GetPublicAccessBlock

Не поддерживается

GetObjectLockConfiguration

Не поддерживается

HeadBucket

Поддерживается

ListBuckets

Поддерживается

ListBucketAnalyticsConfigurations

Не поддерживается

ListBucketInventoryConfigurations

Не поддерживается

ListBucketmetricsConfigurations

Не поддерживается

ListMultipartUploads

Поддерживается

ListObjects

Поддерживается

ListObjectsV2

Поддерживается

ListObjectVersions

Поддерживается

PutBucketAccelerateConfiguration

Не поддерживается

PutBucketAcl

Поддерживается

PutBucketAnalyticsConfiguration

Не поддерживается

PutBucketCors

Поддерживается

PutBucketEncryption

Поддерживается

С ограничениями

PutBucketInventoryConfiguration

Не поддерживается

PutBucketLifecycleConfiguration

Поддерживается

С ограничениями

PutBucketLogging

Не поддерживается

PutBucketMetricsConfiguration

Не поддерживается

PutBucketNotificationConfiguration

Не поддерживается

PutBucketOwnershipControls

Не поддерживается

PutBucketPolicy

Поддерживается

С ограничениями

PutBucketReplication

Не поддерживается

PutBucketRequestPayment

Поддерживается

С ограничениями

PutBucketTagging

Не поддерживается

PutBucketVersioning

Поддерживается

PutBucketWebsite

Поддерживается

PutObjectLockConfiguration

Не поддерживается

PutPublicAccessBlock

Не поддерживается

Операции над объектами#

В таблице описаны методы API для работы с объектами, доступные в AWS S3, и статус их поддержки К2 Облаком.

Функция

Статус

Комментарий

AbortMultipartUpload

Поддерживается

CompleteMultipartUpload

Поддерживается

CreateMultipartUpload

Поддерживается

CopyObject

Поддерживается

DeleteObject

Поддерживается

DeleteObjects

Поддерживается

DeleteObjectTagging

Поддерживается

GetObject

Поддерживается

GetObjectAcl

Поддерживается

GetObjectLegalHold

Не поддерживается

GetObjectRetention

Не поддерживается

GetObjectTagging

Поддерживается

GetObjectTorrent

Не поддерживается

HeadObject

Поддерживается

ListParts

Поддерживается

PostObject

Поддерживается

PutObject

Поддерживается

С ограничениями

PutObjectAcl

Поддерживается

PutObjectLegalHold

Не поддерживается

PutObjectRetention

Не поддерживается

PutObjectTagging

Поддерживается

С ограничениями

RestoreObject

Не поддерживается

SelectObjectContent

Не поддерживается

UploadPart

Поддерживается

S3UploadPartCopy

Поддерживается

Ограничения на поддерживаемые методы#

Ограничения Server Side Encryption#

В рамках AWS S3 поддерживаются две спецификации Server Side Encryption (SSE):

  • SSE-KMS

  • SSE-C

К2 Облако поддерживает только спецификацию SSE-C (см. пример шифрования объекта с её использованием).

Методы Get/Put/DeleteBucketEncryption относятся к спецификации SSE-KMS, которая не поддерживается. Формально методы работают, но воспользоваться шифрованием бакета по спецификации SSE-KMS вы пока не сможете.

Ограничения Bucket Location#

Установка Location с помощью параметра LocationConstraint не поддерживается. Метод GetBucketLocation всегда возвращает null.

Ограничения Bucket Request Payment#

Данный подход не поддерживается. Формально методы Get/PutBucketRequestPayment работают, но воспользоваться этой возможностью вы пока не сможете.

Ограничения Bucket Lifecycle#

Поддерживаются правила для удаления объектов и версий объектов. Не поддерживаются правила перемещения объектов между классами хранения (Storage Classes).

Ограничения 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) для запросов, относящихся к бакетам.

Действие (Action)

Условие (Condition Key)

s3:createBucket

s3:x-amz-acl
s3:x-amz-grant-<perm>, где <perm> одно из разрешений read/write/read-acp/write-acp/full-control

s3:ListBuckets
s3:ListBucketVersions

s3:prefix
s3:delimiter
s3:max-keys

s3:PutBucketAcl

s3:x-amz-acl
s3:x-amz-grant-<perm>, где <perm> одно из разрешений read/write/read-acp/write-acp/full-control

Условия (condition keys) для запросов, относящихся к объектам.

Действие (Action)

Условие (Condition Key)

s3:PutObject

s3:x-amz-acl
s3:x-amz-grant-<perm>, где <perm> одно из разрешений read/write/read-acp/write-acp/full-control
s3:x-amz-copy-source
s3:x-amz-metadata-directive

s3:PutObjectAcl
s3:PutObjectVersionAcl

s3:x-amz-acl
s3-amz-grant-<perm>, где <perm> одно из разрешений read/write/read-acp/write-acp/full-control

Ограничения Object Tagging#

Использование тегов объектов не поддерживается в Bucket Policy, а также в Bucket Lifecycle.

Общий вид запроса#

Вид конкретного запроса зависит от выполняемой операции и передаваемых параметров. Большинство запросов содержит типовые заголовки, в частности аутентифицированные запросы должны включать заголовок Authorization. Если запросы выполняются напрямую из кода, то тогда вам необходимо самостоятельно сгенерировать подпись для заголовка.

Примерный вид запроса#

{GET|HEAD|PUT|DELETE} /<бакет>/<ключ объекта>?<список параметров> HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: <SHA-256 хеш тела запроса>
X-Amz-Date: <Дата в формате ISO08601>
Authorization: <Параметры авторизации в соответствии с AWS Signature Version 4>

<Тело запроса>

Имя бакета и хоста#

Доступ к бакету может осуществляться двумя способами. Первый (предпочтительный) метод идентифицирует бакет как имя хоста (virtual bucket host name).

GET / HTTP/1.1

Host: mybucket.s3.k2.cloud

Второй (унаследованный) метод идентифицирует бакет как каталог высшего уровня URI.

GET /mybucket HTTP/1.1

Host: s3.k2.cloud

Типовые заголовки#

Типовые заголовки запроса#

Данные заголовки используются в большинстве запросов.

Заголовок запроса

Описание

Authorization

Токен авторизации

Content-Length

Длина тела запроса

Content-Type

MIME-тип тела запроса

Date

Время и дата запроса (UTC)

Host

Имя хост-сервера

x-amz-content-sha256

Хеш SHA256 для тела запроса (при аутентификации с помощью AWS Signature Version 4)

Типовые заголовки ответа#

Данные заголовки присутствуют в большинстве ответов.

Заголовок запроса

Описание

Content-Length

Длина тела ответа в байтах

Content-Type

MIME-тип тела запроса, например Application/XML

Date

Дата и время ответа в формате UTC

x-amz-request-id

Идентификатор запроса

Статусы ответа#

При успешном выполнении запроса возвращаются коды 2xx, при невыполнении и ошибке — коды 4xx и 500.

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