Методы
Bucket
Поддерживаемые методы
Метод | Описание |
---|---|
GET Service | Получение списка бакетов |
GET Bucket (List Objects) | Получение списка объектов в бакете |
GET Bucket Location | Получение пула бакета |
DELETE Bucket | Удаление бакета |
HEAD Bucket | Получение статуса бакета |
PUT Bucket | Создание бакета |
GET Service
Описание
Получение списка бакетов. Подробное описание метода.
Пример запроса
GET /
Доступ
Пользователь получает листинг только тех бакетов, к которым он имеет права на чтение или запись.
GET Bucket (List Objects)
Описание
Получение списка объектов в бакете.
Вторая версия обратно-совместима с первой и добавляет поддержку параметров list-type, continuation-token, fetch-owner, start-after. Подробное описание метода.
Пример запроса
GET /<bucketName>
Поддерживаемые параметры
delimiter, marker, max-keys, prefix
Неподдерживаемые параметры
encoding-type
Доступ
Пользователь может получить листинг объектов только того бакета, к которому он имеет право на чтение или запись.
GET Bucket Location
Описание
Получение пула бакета. Подробное описание метода.
Пример запроса
GET /<bucketName>?location
Доступ
Пользователь может получить пул только того бакета, к которому он имеет право на чтение или запись.
DELETE Bucket
Описание
Удаление бакета. Подробное описание метода.
Пример запроса
DELETE /<bucketName>
Доступ
Пользователь может удалить бакет, если он имеет право на запись в этот бакет.
HEAD Bucket
Описание
Заголовок бакета. Подробное описание метода.
Пример запроса
HEAD /<bucketName>
Доступ
Пользователь может получить статус бакета, если он имеет право на чтение или запись в него.
PUT Bucket
Описание
Создание бакета. Подробное описание метода.
Примечание: создание бакета с холодным классом хранения не поддерживается на уровне S3 API.
Пример запроса
PUT /<bucketName>
Неподдерживаемые заголовки
Все ACL.
Доступ
Пользователь может создать бакет, если он имеет право на запись в бакет (не имеет, поэтому и не может создать).
Object
Поддерживаемые методы | Описание метода |
---|---|
GET Object | Получение объекта |
HEAD Object | Получение метаданных объекта |
PUT Object | Создание объекта |
PUT Object — Copy | Копирование объекта |
DELETE Object | Удаление объекта |
GET Object
Описание
Получение объекта. Если объект multipart, то он отдаётся, как цельный объект. Подробное описание метода.
Пример запроса
GET /<bucketName>/<objectName>
Поддерживаемые заголовки
Range
Неподдерживаемые заголовки
Все заголовки с префиксом “If-”, “x-amz-server-side-encryption-”
Поддерживаемые параметры
Все параметры с префиксом “response-”
Неподдерживаемые параметры
partNumber, versionId
Доступ
Пользователь может получить объект, если он имеет право на чтение или запись в бакет.
HEAD Object
Описание
Получение метаданных объекта. Подробное описание метода.
Пример запроса
HEAD /<bucketName>/<objectName>
Неподдерживаемые заголовки
Все с префиксом “If-”, “x-amz-server-side-encryption-”
Неподдерживаемые параметры
partNumber, versionId
Доступ
Пользователь может получить метаданные объекта, если он имеет право на чтение или запись в бакет.
PUT Object
Описание
Создание объекта. Подробное описание метода.
Пример запроса
PUT /<bucketName>/<objectName>
Поддерживаемые заголовки
Cache-Control, Content-Disposition, Content-Encoding, Content-Language, Content-Type, Expires, “x-amz-meta-”
Неподдерживаемые заголовки
Content-MD5, x-amz-storage-class, x-amz-tagging, x-amz-website-redirect-location, префикс “x-amz-object-lock-”, ACL, префикс “x-amz-server-side-encryption-”
Доступ
Пользователь может создать объект, если он имеет право на запись в бакет.
PUT Object — Copy
Описание
Копирование объекта. При копировании объекта самого в себя выполняется модификация метаданных объекта. Подробное описание метода.
Пример запроса
PUT /<bucketName>/<objectName> (x-amz-copy-source)
Поддерживаемые заголовки
Cache-Control, Content-Disposition, Content-Encoding, Content-Language, Content-Type, Expires, “x-amz-meta-”, x-amz-copy-source, x-amz-metadata-directive
Неподдерживаемые заголовки
префикс “x-amz-copy-source-if-”, ACL, x-amz-storage-class, x-amz-tagging-directive, x-amz-website-redirect-location, префикс “x-amz-server-side-encryption-”
Доступ
Пользователь может скопировать объект, если он имеет право на чтение или запись в бакет-источник.
DELETE Object
Описание
Удаление объекта.
Если объект multipart, то помимо манифеста удаляются все его части из контейнера с сегментами.
Примечание: данный метод не возвращает ошибок.
Пример запроса
DELETE /<bucketName>/<objectName>
Неподдерживаемые заголовки
x-amz-mfa
Неподдерживаемые параметры
versionId
Доступ
Пользователь может удалить объект, если он имеет право на запись в бакет.
Multipart Upload
Составная загрузка позволяет загружать отдельный объект по частям. Загрузку частей можно производить независимо от остальных, что позволяет дозагружать части в случае, если передача была прервана.
Примечание: при работе с S3 при Multipart-загрузке больших объектов все загруженные сегменты не собираются в финале в единый объект, а складируются в соседний контейнер с таким же именем и суффиксом _s3multipartuploads
.
В общем виде, если размер вашего объекта больше 100 МБ — необходимо использовать составную загрузку.
Загрузка выполняется в три этапа:
Инициализация
Происходит проверка на наличие объекта с таким же именем. Если объект уже существует, то он удаляется.
Создается контейнер с именем текущего, к нему добавляется суффикс _s3multipartuploads
. Далее там будут храниться сегменты загруженного объекта.
Генерируется uploadId.
В контейнере с сегментами создаётся мета-объект /uploads/<bucketName>_s3multipartuploads/<objectName>_<uploadId>/
, который будет хранить Content-Type и все пользовательские метаданные до финализации.
Загрузка частей (сегментов)
Происходит загрузка сегментов.
Финализация
Делается листинг всех объектов по префиксу <bucketName>_s3multipartuploads/<objectName>/<uploadId>/
и сравнивается с листингом, который пришел от клиента.
Считается суммарный размер объекта и суммируются хэши.
Создаётся манифест, который будет находиться по пути загружаемого multipart-объекта.
Из созданного ранее мета-объекта считывается Content-Type и пользовательские метаданные и записываются в манифест, а сам мета-объект затем удаляется.
Поддерживаемы методы
Метод | Описание |
---|---|
Initiate Multipart Upload | Инициирование загрузки multipart-объекта |
Complete Multipart Upload | Финализация загрузки multipart-объекта |
Abort Multipart Upload | Отмена загрузки multipart-объекта |
List Multipart Uploads | Получение списка загружаемых multipart-объектов |
Delete Multiple Objects | Множественное удаление объектов в бакете |
List Parts | Получение списка сегментов multipart-объекта |
Upload Part | Загрузка части multipart-объекта |
Upload Part — Copy | Копирование части multipart-объекта |
Initiate Multipart Upload
Описание
Инициирование загрузки multipart-объекта.
При инициировании multipart upload поверх существующего объекта — он удаляется. Также создается контейнер для сегментов, если отсутствует, и в него по определённому префиксу кладётся meta-объект с метаданными.
Пример запроса
POST /<bucketName>/<objectName>?uploads
Поддерживаемые параметры
Cache-Control, Content-Disposition, Content-Encoding, Content-Language, Content-Type, Expires, “x-amz-meta-”
Неподдерживаемые параметры
x-amz-storage-class, x-amz-tagging, x-amz-website-redirect-location, ACL, префикс “x-amz-server-side-encryption-”
Доступ
Пользователь может инициировать multipart upload, если он имеет право на запись в бакет.
Complete Multipart Upload
Описание
Финализация загрузки multipart-объекта.
По префиксу с переданным uploadId делается листинг объектов и сравнивается с листингом объектов в теле запроса. Из meta-объекта забираются сохранённые метаданные, а сам объект уничтожается.
Пример запроса
POST /<bucketName>/<objectName>?uploadId=<uploadId>
Доступ
Пользователь может финализировать multipart upload, если он имеет право на запись в бакет.
Abort Multipart Upload
Описание
Отмена загрузки multipart-объекта.
Удаляется каждый загруженный сегмент, затем и мета-объект.
Пример запроса
DELETE /<bucketName>/<objectName>?uploadId=<uploadId>
Доступ
Пользователь может отменить загрузку multipart-объекта., если он имеет право на запись в бакет.
List Multipart Uploads
Описание
Получение списка загружаемых multipart-объектов.
Работает только между этапами Инициализации и Финализации.
Пример запроса
GET /<bucketName>?uploads
Поддерживаемые параметры
delimiter (только “/”), max-uploads, key-marker, prefix, upload-id-marker
Неподдерживаемые параметры
encoding-type
Доступ
Пользователь может получить листинг загружаемых multipart-объектов только того бакета, к которому он имеет право на чтение или запись.
Delete Multiple Objects
Описание
Множественное удаление объектов в бакете.
Пример запроса
POST /<bucketName>?delete
Неподдерживаемые параметры
VersionId
Поддерживаемые заголовки
Content-MD5
Неподдерживаемые заголовки
x-amz-mfa
Доступ
Пользователь может удалить объект, если он имеет право на запись в бакет.
List Parts
Описание
Получение списка сегментов multipart-объекта.
Работает только между этапами Инициализации и Финализации.
Пример запроса
GET /<bucketName>/<objectName>?uploadId=<uploadId>
Поддерживаемые параметры
uploadId, max-parts, part-number-marker
Неподдерживаемые параметры
encoding-type
Доступ
Пользователь может получить список сегментов, если он имеет право на чтение или запись в бакет.
Upload Part
Описание
Загрузка части multipart-объекта.
В этом методе к имени бакета добавляется "_s3multipartuploads"
, а путь к объекту заменяется на "<objectName>/<uploadId>/<partNumber>"
.
Пример запроса
PUT /<bucketName>/<objectName>?partNumber=<partNumber>&uploadId=<uploadId>
Неподдерживаемые параметры
Expect, Content-MD5, префикс “x-amz-server-side-encryption-”
Доступ
Пользователь может создать часть multipart-объекта, если он имеет право на запись в бакет.
Upload Part - Copy
Описание
Копирование части multipart-объекта.
Пример запроса
PUT /<bucketName>/<objectName>?partNumber=<part_number>&uploadId=<uploadId> (x-amz-copy-source)
Поддерживаемые параметры
x-amz-copy-source
Неподдерживаемые параметры
x-amz-copy-source-range, префикс “x-amz-copy-source-if-”, “x-amz-server-side-encryption-”
Доступ
Пользователь может скопировать часть multipart-объекта, если он имеет право на чтение или запись в бакет-источник.
POST Upload
Загружать файлы в хранилище можно через HTML-форму. HTML-форма содержит POST-политику (POST Policy) в формате JSON и кодировке base64, которая устанавливает правила и ограничения на загрузку файлов. Загрузка объектов через HTML-форму без политики невозможна. Подробнее о создании политик в документации Amazon.
Реализовать логику создания POST-политики
В политику можно добавлять разные правила и ограничения. Пример готовой POST-политики:
{ "expiration": "<expiration>",
"conditions": [
{"bucket": "<bucket_name>"},
["starts-with", "$key", "<path>"],
{"success_action_redirect": "<redirect_url>"},
{"x-amz-credential": "ACCESS_ID/YYYYMMDD/REGION/s3/aws4_request"},
{"x-amz-algorithm": "AWS4-HMAC-SHA256"},
{"x-amz-date": "<date>" }
]
}
Укажите:
<expiration>
— дату и время (в формате ISO8601), когда подпись станет невалидной и форма перестанет работать;<bucket_name>
— имя контейнера;<path>
— префикс, который должен быть у файлов;<redirect_url>
— опционально: URL, на который будет произведено перенаправление после загрузки файла;<date>
— дату в формате ISO8601.
Типы правил и ограничений
Поле conditions
содержит набор правил и ограничений формы.
Тип правила | Описание | Пример правила |
---|---|---|
Полное совпадение | Значение в поле формы должно совпадать со значением, которое указано в правиле | [ "eq", "$content-typel", "image/jpeg" ] ) |
Частичное совпадение | Значение в поле формы должно начинаться со строки, которая указана в правиле | ["starts-with", "$key", "user/user1/"] |
Соответствие диапазону | Значение в поле формы должно попадать в указанный диапазон | ["content-length-range", 1048576, 10485760] |
Для полей формы можно устанавливать правила разных типов.
Имя поля | Типы правил | Область ограничения |
---|---|---|
bucket |
Полное совпадение | Имя бакета |
content-length-range |
Соответствие диапазону | Объем, которому должен соответствовать размер файла |
Cache-Control Content-Type Content-Disposition Content-Encoding Expires |
Полное совпадение; частичное совпадение |
Одноименные HTTP-заголовки |
key |
Полное совпадение; частичное совпадение |
Префикс имени объекта |
success_action_redirect |
Полное совпадение; частичное совпадение |
URL, на который будет произведено перенаправление после загрузки файла |
success_action_status |
Полное совпадение | Код, который будет возвращен пользователю после загрузки файла, если поле success_action_redirect не указано |
x-amz-algorithm |
Полное совпадение | Алгоритм для подписи политики (всегда AWS4-HMAC-SHA256 ) |
x-amz-credential |
Полное совпадение | Идентификатор подписи |
x-amz-date |
Полное совпадение | Дата в формате ISO8601. Должна совпадать со значение даты из поля x-amz-credential |
x-amz-meta-* |
Полное совпадение; частичное совпадение |
Пользовательские метаданные объекта |
Добавить HTML-форму на сайт
Форма может иметь вид:
<form action="https://BUCKET_NAME.s3.storage.selcloud.ru/" method="post" enctype="multipart/form-data">
Key to upload:
<input type="input" name="key" value="PATH/${FILENAME}" /><br />
<input type="hidden" name="success_action_redirect" value="REDIRECT_URL" />
Content-Type:
<input type="input" name="Content-Type" value="Content type" /><br />
<input type="text" name="X-Amz-Credential" value="ACCESS_KEY_ID/YYYYMMDD/REGION/s3/aws4_request" />
<input type="text" name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" />
<input type="text" name="X-Amz-Date" value="DATE" />
<input type="hidden" name="Policy" value='Base64-encoded policy string' />
<input type="hidden" name="X-Amz-Signature" value="SIGNATURE_VALUE" />
File:
<input type="file" name="file" /> <br />
<input type="submit" name="submit" value="Upload to S3" />
</form>
Здесь:
-
action="https://BUCKET_NAME.s3.storage.selcloud.ru/"
— URL для загрузки объектов; -
name="key" value="PATH/${filename}"
— путь к файлу, гдеPATH
— префикс. В поле${filename}
будет автоматически подставлено имя загружаемого объекта; -
name="X-Amz-Credential" value="ACCESS_KEY_ID/YYYYMMDD/REGION/s3/aws4_request"
— идентификатор для подписи, где:ACCESS_KEY_ID
— имя пользователя;YYYYMMDD
— текущая дата;REGION
— пул размещения контейнера, в который будут загружаться объекты (ru-1);
-
name="X-Amz-Date" value="DATE"
— дата в формате ISO8601; -
name="Policy" value='Base64-encoded policy string'
— POST-политика в формате JSON, закодированная в base64; -
name="X-Amz-Signature" value="SIGNATURE_VALUE"
— подпись POST-политики в формате HMAC-SHA256.
CORS
Cross-Origin Resource Sharing (CORS) позволяет ограничивать доступ к ресурсам из разных источников.
Пример CORS-конфигурации
{
"CORSRules": [
{
"AllowedOrigins": ["http://www.example.com"],
"AllowedHeaders": ["*"],
"AllowedMethods": ["PUT", "POST", "DELETE"],
"MaxAgeSeconds": 3000,
"ExposeHeaders": ["x-amz-server-side-encryption"]
},
{
"AllowedOrigins": ["*"],
"AllowedHeaders": ["Authorization"],
"AllowedMethods": ["GET"],
"MaxAgeSeconds": 3000
}
]
}
Такая конфигурация разрешает отправлять запросы PUT, POST, DELETE с ресурса http://www.example.com
с любыми заголовками, раскрывает заголовок x-amz-server-side-encryption
для клиента и разрешает GET-запросы с любого ресурса с заголовком Authorization
.
Методы
Метод | Описание |
---|---|
PUT Bucket CORS | Установка CORS конфигурации бакета |
GET Bucket CORS | Получение CORS конфигурации бакета |
DELETE Bucket CORS | Удаление CORS конфигурации бакета |
PUT Bucket CORS
Установка CORS конфигурации на бакет. Если конфигурация уже существует, она будет перезаписана.
Пример запроса:
aws s3api put-bucket-cors --bucket cors-example --cors-configuration file://cors.json --endpoint-url=[https://s3.storage.selcloud.ru](https://s3.storage.selcloud.ru) --debug
GET Bucket CORS
Получение CORS конфигурации бакета.
Пример запроса:
aws s3api get-bucket-cors --bucket cors-example --endpoint-url=[https://s3.storage.selcloud.ru](https://s3.storage.selcloud.ru)
{
"CORSRules": [
{
"AllowedHeaders": [
"*"
],
"AllowedMethods": [
"PUT",
"POST",
"DELETE"
],
"AllowedOrigins": [
"http://www.example.com"
],
"ExposeHeaders": [
"x-amz-server-side-encryption"
],
"MaxAgeSeconds": 3000
},
{
"AllowedHeaders": [
"Authorization"
],
"AllowedMethods": [
"GET"
],
"AllowedOrigins": [
"*"
],
"MaxAgeSeconds": 3000
}
]
}
DELETE Bucket CORS
Удаление CORS конфигурации бакета.
Пример запроса:
DELETE /?cors