Как пользоваться S3 API

Подготовка к работеПодготовка к работе

Чтобы воспользоваться API:

1. Создайте сервисный аккаунт.

2. Назначьте сервисному аккаунту роли, которые нужны для вашего проекта, например storage.editor на бакет — для работы с конкретным бакетом, или на каталог — для работы со всеми бакетами в каталоге. Подробнее о ролях см. на странице Управление доступом с помощью Yandex Identity and Access Management.

   Чтобы работать с объектами в зашифрованном бакете, у пользователя или сервисного аккаунта вместе с ролью storage.configurer должны быть следующие роли на ключ шифрования:

   • kms.keys.encrypter — для чтения ключа, шифрования и загрузки объектов;
   • kms.keys.decrypter — для чтения ключа, расшифровки и скачивания объектов;
   • kms.keys.encrypterDecrypter — включает разрешения, предоставляемые ролями kms.keys.encrypter и kms.keys.decrypter.

   Подробнее см. Сервисные роли Key Management Service.

3. Создайте статический ключ доступа.

   В результате вы получите данные статического ключа доступа. Для аутентификации в Object Storage вам понадобятся:

   • key_id — идентификатор статического ключа доступа;
   • secret — секретный ключ.

   Сохраните key_id и secret, так как повторное получение значения ключа будет невозможно.

Авторизация статическими ключами необходима для обращения напрямую к HTTP API и поддерживается инструментами, перечисленными в разделе Поддерживаемые инструменты.

Статический ключ для доступа к Object Storage можно безопасно хранить в сервисе Yandex Lockbox. Подробнее см. Использование секрета Yandex Lockbox для хранения статического ключа доступа.

Перечень поддерживаемых методов Amazon S3 HTTP API смотрите в Справочнике API.

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

Общий вид запроса к Object Storage API:

{GET|HEAD|PUT|DELETE} /<имя_бакета>/<ключ_объекта> HTTP/2
Host: storage.yandexcloud.net
Content-Length: length
Date: date
Authorization: authorization string (AWS Signature Version 4)

Request_body

Запрос содержит HTTP-метод, имя бакета и ключ объекта.

Имя бакета можно указать как часть имени хоста. В этом случае запрос примет вид:

{GET|HEAD|PUT|DELETE} /<ключ_объекта> HTTP/2
Host: <имя_бакета>.storage.yandexcloud.net
...

Набор заголовков зависит от конкретного запроса и описан в документации на соответствующий запрос.

Если вы используете API напрямую (без SDK и приложений), то для подписи запросов вам придется самостоятельно генерировать заголовок Authorization. О том, как это сделать, читайте в разделе Authenticating Requests (AWS Signature Version 4) документации Amazon S3.

Отрабатывать процесс формирования запроса и подписи вы можете с помощью AWS CLI в режиме отладки.

Чтобы отправить подписанный запрос к S3 API, вы можете использовать утилиту curl.

URL для запросаURL для запроса

URL может иметь одну из следующих форм:

• http(s)://storage.yandexcloud.net/<имя_бакета>/<ключ_объекта>?<query-параметры>
• http(s)://<имя_бакета>.storage.yandexcloud.net/<ключ_объекта>?<query-параметры>

URL содержит имя бакета, ключ объекта и query-параметры. Пример возможных query-параметров см. в описании метода для получения объекта.

CORS запросыCORS запросы

Кросс-доменные запросы доступны для всех методов API, которые управляют объектами.

Для проверки разрешений CORS подразумевает предварительный запрос options к ресурсу. Object Storage позволяет отправлять кросс-доменные запросы к ресурсам без предварительного запроса, при этом в запросе должны быть те же заголовки, что и у предварительного запроса.

См. такжеСм. также

• Отладка запросов с помощью утилиты AWS CLI
• Пример отправки подписанного запроса с помощью утилиты curl
• Пример кода для генерации подписи