Обращение к хранилищу¶

Страница нужна разработчику, который подключает клиент S3 к S3R. Она описывает, какие клиенты подходят, как задать адрес и подписать запрос, как устроены ключи и метаданные объектов и какие операции S3 API поддерживаются. Отдельные операции разобраны на страницах Операции с объектами, Настройки бакета и Управление доступом.

Совместимость с клиентами¶

Работает любой клиент протокола S3 с подписью версии 4, например aws-sdk-go, aws-sdk-java, boto3, aws-sdk-cpp, aws-cli, s3cmd, rclone и mc. Собственного протокола плагин не вводит. В настройках клиента задаются:

адрес эндпоинта;
ключ доступа (см. Учётные данные);
адресация в формате пути (см. Адресация).

Подпись запросов¶

Запросы подписываются по схеме AWS Signature Version 4. Подпись передаётся:

в заголовке;
в параметрах запроса — так устроена заранее подписанная ссылка.

Для передачи тела запроса частями поддерживается потоковая подпись STREAMING-AWS4-HMAC-SHA256-PAYLOAD (см. Потоковая загрузка).

Адресация¶

Поддерживаются две формы адреса:

Форма	Вид адреса	Когда доступна
Путь (по умолчанию)	`https://s3.example.net/бакет/ключ`	всегда
Виртуально-хостовая: имя бакета входит в доменное имя	`бакет.FQDN`	только для тенанта с заданным FQDN

Адресация в формате пути включается в клиенте параметром addressing_style: path или флагом force_path_style. На точке входа по умолчанию, то есть при обращении по IP-адресу или имени узла, это единственная поддерживаемая форма.

Тенант с заданным FQDN отвечает и по своему FQDN, и в форме бакет.FQDN. Для второй формы нужна запись DNS с подстановочным знаком на FQDN тенанта. См. Изоляция тенантов.

Примеры обращения¶

Настройка профиля и работа через AWS CLI:

aws configure set aws_access_key_id AKIA...
aws configure set aws_secret_access_key ...

aws --endpoint-url https://s3.example.net s3 mb s3://documents
aws --endpoint-url https://s3.example.net s3 cp report.pdf s3://documents/
aws --endpoint-url https://s3.example.net s3 ls s3://documents/
aws --endpoint-url https://s3.example.net s3 rm s3://documents/report.pdf

Обращение из Python:

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.example.net",
    aws_access_key_id="AKIA...",
    aws_secret_access_key="...",
    config=Config(s3={"addressing_style": "path"}),
)
s3.put_object(Bucket="documents", Key="report.pdf", Body=data)

Сокращение в примерах

Далее в примерах вместо aws --endpoint-url https://s3.example.net пишется aws.

Гарантии согласованности¶

Записанный объект сразу доступен для чтения. Метаданные читаются с мастера репликасета, и операции с одним ключом линеаризуемы.
Объект появляется целиком или не появляется вовсе. Сначала сохраняется содержимое, затем создаётся запись об объекте, и только после этого объект становится виден. Прерванная запись не оставляет частично записанного объекта.
При нескольких площадках ответ на запись подтверждает сохранение на одной площадке. Копии на остальные площадки создаются после ответа. Объект при этом виден на всех площадках сразу: пока копии нет, содержимое запрашивается с площадки, где оно есть (см. Репликация между площадками).

Исключение: чтение с реплик

Если администратор задал параметр read_preference = any, чтение объектов и списки могут вернуть устаревшие данные: только что записанный объект не находится, удалённый ещё читается (см. Чтения возвращают устаревшие данные). По умолчанию параметр равен leader.

Что приложение получает при отказах и перегрузке, описано на странице Ошибки и повторные запросы.

Поддерживаемые операции¶

Не поддерживаются шифрование на стороне сервера, настройка репликации через S3 API, журналирование доступа к бакету, уведомления, восстановление из архивного класса, S3 Select и каталожные бакеты S3 Express. Остальные операции перечислены в таблице по алфавиту.

Нереализованная операция, как правило, возвращает NotImplemented. Проверка доступа может выполняться раньше выбора обработчика, поэтому запрос без требуемых прав получит ответ AccessDenied.

Операция	Есть	Примечание
`AbortMultipartUpload`	да
`CompleteMultipartUpload`	да	условная публикация `If-Match` и `If-None-Match`
`CopyObject`	да	`CopySource` с `versionId`, директивы `COPY` и `REPLACE`
`CreateBucket`	да	в том числе `ObjectLockEnabledForBucket`
`CreateMultipartUpload`	да
`DeleteBucket`	да	только для пустого бакета; см. Удаление бакета
`DeleteBucketCors`	да
`DeleteBucketEncryption`	нет	шифрование на стороне сервера не реализовано
`DeleteBucketLifecycle`	да
`DeleteBucketPolicy`	да
`DeleteBucketReplication`	нет	репликация между площадками настраивается не через S3 API
`DeleteBucketTagging`	да
`DeleteBucketWebsite`	да	удаляет конфигурацию; сайт не отдаётся, см. Ограничения
`DeleteObject`	да	в том числе удаление конкретной версии
`DeleteObjects`	да	до 1000 ключей, результат по каждому ключу отдельно
`DeleteObjectTagging`	да
`DeletePublicAccessBlock`	да
`GetBucketAcl`	да
`GetBucketCors`	да	404, если правила не задавались
`GetBucketEncryption`	нет
`GetBucketLifecycleConfiguration`	да
`GetBucketLocation`	да	регион задаётся параметром `region`
`GetBucketLogging`	нет
`GetBucketNotificationConfiguration`	нет	уведомлений в очереди сообщений нет
`GetBucketPolicy`	да	документ возвращается без изменений
`GetBucketPolicyStatus`	да
`GetBucketReplication`	нет
`GetBucketTagging`	да
`GetBucketVersioning`	да
`GetBucketWebsite`	да	без конфигурации отвечает `NoSuchWebsiteConfiguration`
`GetObject`	да	`Range`, `PartNumber`, условные заголовки, `versionId`
`GetObjectAcl`	да
`GetObjectAttributes`	да	`Checksum`, `ObjectParts` с размерами и смещениями; `ETag` возвращается в кавычках
`GetObjectLegalHold`	да
`GetObjectLockConfiguration`	да
`GetObjectRetention`	да	режимы `GOVERNANCE` и `COMPLIANCE`
`GetObjectTagging`	да
`GetPublicAccessBlock`	да	404, если настройка не задавалась
`HeadBucket`	да
`HeadObject`	да	условные заголовки, `PartNumber`, `versionId`
`ListBuckets`	да	в том числе `max-buckets` и `continuation-token`
`ListDirectoryBuckets`	нет	каталожные бакеты S3 Express не поддерживаются
`ListMultipartUploads`	да
`ListObjects`	да
`ListObjectsV2`	да
`ListObjectVersions`	да
`ListParts`	да
`POST Object`	да	загрузка формой из браузера; см. Ограничения
`PutBucketAcl`	да
`PutBucketCors`	да	до 100 правил, документ проверяется при записи
`PutBucketEncryption`	нет
`PutBucketLifecycleConfiguration`	да
`PutBucketLogging`	нет
`PutBucketNotificationConfiguration`	нет
`PutBucketPolicy`	да	документ проверяется при записи
`PutBucketReplication`	нет
`PutBucketTagging`	да
`PutBucketVersioning`	да	`Enabled` и `Suspended`
`PutBucketWebsite`	да	конфигурация сохраняется целиком; сайт не отдаётся
`PutObject`	да	условная запись `If-Match` и `If-None-Match`, контрольные суммы SHA-256 и CRC64/NVME
`PutObjectAcl`	да
`PutObjectLegalHold`	да
`PutObjectLockConfiguration`	да
`PutObjectRetention`	да
`PutObjectTagging`	да
`PutPublicAccessBlock`	да	четыре флага, заменяются целиком
`RestoreObject`	нет	архивного класса хранения нет
`SelectObjectContent`	нет	S3 Select не поддерживается
`UploadPart`	да	контрольные суммы SHA-256 и CRC64/NVME
`UploadPartCopy`	да	в том числе `copy-source-range`