Документация к API/Облачные услуги/Объектное хранилище/S3 API/

Методы

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-политики.
Добавьте HTML-форму.

Реализовать логику создания 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