--- title: "Описание принципов работы с S3 — База знаний Timeweb Cloud" description: "Описание принципов работы с S3. Документация и инструкции по управлению IT-инфраструктурой. Timeweb Cloud — облачные решения для вашего бизнеса." --- # Описание принципов работы с S3 > Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt). Подробный гайд по принципам работы с S3-хранилищем.  ## Реквизиты подключения Данные для подключения к S3 можно найти во вкладке «Дашборд» в [панели управления](https://timeweb.cloud/my/storage) в настройках нужного бакета. ![Selection 252](https://content.timeweb.com/assets/80cb31aa-f2a6-4581-99ab-f74b22e13a0c.png?width=1012&height=939) На текущий момент реализована поддержка `AWS Signature V2` и `AWS Signature V4`. Для подтверждения личности запрашивающего все запросы должны иметь подпись, которую можно создать с помощью `Access Key` и `Secret Key`. ## Вычисление подписи Вычисление подписи состоит из трех шагов: 1. Получение ключа подписи (`SigningKey`) 2. Получение строки для подписи (`StringToSign`) 3. Подпись строки с помощью ключа ### Получение ключа для подписи (SigningKey) Для получения подписывающего ключа закодируйте с помощью алгоритма `HMAC-SHA256` следующие данные: ```shell DateKey = HMAC-SHA256("AWS4"+"", "") DateRegionKey = HMAC-SHA256(, "") DateRegionServiceKey = HMAC-SHA256(, "") SigningKey = HMAC-SHA256(, "aws4_request") ``` Мы поддерживаем метод подписи запросов через HTTP-заголовок `Authorization`. Использование заголовка `Authorization` является наиболее частным методом аутентификации пользователя. Общий вид запроса: ```shell Authorization: AWS4-HMAC-SHA256 Credential=12345_USER/20180524/ru-1/s3/aws4_request, SignedHeaders=host;range;x-amz-date, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024 ``` Описание параметров запроса: | **Параметр** | **Описание** | | --- | --- | | AWS4-HMAC-SHA256 | Подпись AWS версии 4 (AWS4) и алгоритм подписи (HMAC-SHA256) | | Credential | Содержит ключ доступа и информацию о запросе в формате: ${ACCESS_KEY}/${YYYYMMDD}/${REGION}/s3/aws4_request | | SignedHeaders | Список в нижнем регистре имен заголовков запроса, используемых при вычислении подписи | | Signature | Подписанный хэш, состоящий из хэша тела запроса, секретного ключа и информации о запросе (каноническом запросе) | ### Получение строки для подписи Для того чтобы получить строку для подписи, необходимо сделать канонический запрос следующего вида: ``` \n \n \n \n \n ``` Где: - `HTTPMethod` — один из HTTP-методов, например `GET`, `PUT`, `HEAD` и `DELETE`; - `CanonicalURI` — URI-кодированная часть адреса, которая начинается после домена, с первым «/», например для `https://s3.twcstorage.ru/bucket/sample.txt` будет выглядеть следующим образом: `/bucket/sample.txt`; - `CanonicalQueryString` — параметры строки запроса; - `CanonicalHeaders` — список заголовков и их значений, разделенных новой строкой, в нижнем регистре и без пробелов; - `SignedHeaders` — список имен заголовков без значений, отсортированных по алфавиту, в нижнем регистре и через точку с запятой. Например: `host;x-amz-content-sha256;x-amz-date`; - `HashedPayload` — хэш `SHA256` тела запроса `Hex(SHA256Hash())`. В случае, если тела запроса нет, хэш необходимо посчитать от пустой строки `Hex(SHA256Hash(“”))`. ### Подпись строки с помощью ключа Строка для подписи представляет собой конкатенацию следующих строк: ``` "AWS4-HMAC-SHA256" + "\n" + timeStampISO8601Format + "\n" + + "\n" + Hex(SHA256Hash()) ``` Где: - `AWS4-HMAC-SHA256` — данная строка определяет алгоритм шифрования, который вы используете; - `timeStampISO8601Format` — текущее UTC-время в формате ISO 8601 (например, `20130524T000000Z`); - `Scope` — строка формата `date.Format() + "/" + + "/" + + "/aws4_request"`, например `“20130606/ru-1/s3/aws4_request”`, привязывает полученную подпись к определенной дате, региону или сервису. В случае привязки к дате, подпись будет действовать 15 минут. Подробнее о способе аутентификации через заголовок `Authorization` читайте в официальной документации [Amazon S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html). ## Поддержка методов S3 Основные методы S3, которые поддерживает хранилище Timeweb Cloud, перечислены ниже. Список всех функций и дополнительную информацию можно найти в [официальной документации](https://docs.ceph.com/en/latest/radosgw/s3/#features-support). ### Методы для работы с бакетами | **Метод** | **Описание** | | --- | --- | | GET Service (List Buckets) | Получение списка бакетов | | GET Bucket (List Objects) | Получение списка объектов в бакете | | GET Bucket Location | Получение региона бакета | | DELETE Bucket | Удаление бакета | | HEAD Bucket | Получение статуса бакета | | PUT Bucket | Создание бакета | | GET Bucket ACL | Получение списка управления доступом (access control list) | | PUT Bucket ACL | Назначение списка управления доступом | | GET Bucket Multipart Uploads | Получение списка текущих составных загрузок | | PUT Bucket Versioning (Enable / Suspend) | Включение или выключение версионирования бакета | | GET Bucket Versioning | Получение статуса версионирования (метод не вернет статус, если состояние версионирования не было ранее установлено методом PUT) | | PUT Notification | Включение уведомлений о событиях для бакета | | DELETE Notification | Удаление уведомлений о событиях для бакета | | GET Notification | Получения списка уведомлений для бакета | | GET Bucket Lifecycle | Получение конфигурации жизненного цикла бакета | | DELETE Bucket Lifecycle | Удаление конфигурации жизненного цикла бакета | | PUT Bucket Tagging | Добавление меток бакету | | GET Bucket Tagging | Получение меток бакета | | DELETE Bucket Tagging | Удаление меток бакета | | GET Bucket Policy | Получение политики доступа для бакета | | PUT Bucket Policy | Применение политики доступа для бакета | | DELETE Bucket Policy | Удаление политики доступа для бакета | ### Методы для работы с объектами | **Метод** | **Описание** | | --- | --- | | PUT Object | Создание объекта | | PUT Object — Copy | Копирование объекта | | DELETE Object | Удаление объекта | | GET Object | Получение объекта | | HEAD Object | Получение метаданных объекта | | GET Object ACL | Получение списка управления доступом для объекта | | PUT Object ACL | Назначение списка управления доступом для объекта | | POST Multipart Upload | Запуск составной загрузки | | PUT Multipart Upload Part | Загрузка части объекта | | GET Multipart Upload Parts | Получение загруженных частей составной загрузки | | POST Multipart Upload (Complete) | Завершение составной загрузки | | DELETE Multipart Upload | Прерывание составной загрузки | | PUT Object Tagging | Добавление меток для объекта | | GET Object Tagging | Получение меток объекта | | DELETE Object Tagging | Удаление меток объекта | ## Примеры использования AWS SDK для разных языков Примеры использования SDK вы можете найти в разделе «[SDK для S3](https://timeweb.cloud/docs/s3-storage/sdk)» и в репозиториях GitHub: - [Node.js](https://github.com/timeweb-cloud/s3-examples/tree/master/nodejs)  - [Python3](https://github.com/timeweb-cloud/s3-examples/tree/master/python3) - [PHP](https://github.com/timeweb-cloud/s3-examples/tree/master/php)