Справочник API

Аутентификация — это способ убедиться, что запрос исходит от доверенного пользователя или сервиса.

Основные типы аутентификации

Тип	Описание
Access Key / Secret Key	Пара ключей, которая используется для подписи запросов. Сервис проверяет подпись и разрешает доступ.
IAM (Identity and Access Management)	Централизованное управление пользователями, группами и ролями. Позволяет выдавать права доступа к ресурсам и управлять временными токенами.
Временные токены	Используются для временного доступа к ресурсам, например, через STS (Security Token Service).
Pre-signed URL	Временная ссылка, которая позволяет анонимному пользователю получить доступ к объекту без прямой аутентификации.

Механизм проверки подписи

Клиент формирует строку с параметрами запроса.
Подписывает ее с помощью Secret Key.
Сервис проверяет подпись и сравнивает с ожидаемой.
Если подпись верна, запрос разрешен.

Примеры запросов аутентификации

Пример GET-запроса (через curl)

curl -X GET "https://my-bucket.storage.turbocloud.ru/example.txt"   -H "Authorization: AWS4-HMAC-SHA256 Credential=ACCESS_KEY/20251015/ru-central1/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=SIGNATURE"   -H "x-amz-date: 20251015T120000Z"

ACCESS_KEY / SECRET_KEY — ключи, выданные сервисом;
SIGNATURE — генерируется на основе запроса и Secret Key с указанием внутреннего региона.

Пример pre-signed URL

import boto3

s3_client = boto3.client(
    's3',
    endpoint_url='https://storage.turbocloud.ru',
    aws_access_key_id='ACCESS_KEY',
    aws_secret_access_key='SECRET_KEY'
)

url = s3_client.generate_presigned_url(
    'get_object',
    Params={'Bucket': 'my-bucket', 'Key': 'example.txt'},
    ExpiresIn=3600
)

print(url)

Примечание: endpoint_url указывает на S3-совместимый сервис.

Пример GET-запроса получения объекта для AWS S3 (через curl)

curl -X GET "https://my-bucket.s3.amazonaws.com/example.txt"   -H "Authorization: AWS4-HMAC-SHA256 Credential=ACCESS_KEY/20251015/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=SIGNATURE"   -H "x-amz-date: 20251015T120000Z"

ACCESS_KEY / SECRET_KEY — ваши ключи доступа;
SIGNATURE генерируется на основе запроса и Secret Key;
x-amz-date — дата запроса в формате UTC.

Пример pre-signed URL для AWS S3 (Python)

import boto3

s3_client = boto3.client('s3', region_name='us-east-1')

url = s3_client.generate_presigned_url(
    'get_object',
    Params={'Bucket': 'my-bucket', 'Key': 'example.txt'},
    ExpiresIn=3600
)

print(url)

Примечание: любой пользователь с этой ссылкой сможет скачать объект example.txt в течение 1 часа.

gRPC и REST для работы с объектным хранилищем

gRPC

Протокол удаленного вызова процедур на базе HTTP/2, который использует бинарный формат передачи данных (Protobuf).

Преимущества: высокая производительность, поддержка стриминга;
Недостатки: сложнее дебажить вручную, требует генерации клиентских библиотек.

REST

Протокол на базе HTTP/1.1 или HTTP/2, который использует текстовый формат (JSON/XML) для передачи данных.

Преимущества: простота использования, легко отлаживать работу программ через браузер или командную утилиту curl;
Недостатки: чуть больше нагрузка на сеть, нет встроенной поддержки стриминга.

Когда что использовать?

Протокол	Когда использовать
REST	Внешние API, интеграции с клиентами, совместимость с Amazon S3.
gRPC	Высокопроизводительные системы, стриминг данных, внутренняя коммуникация между сервисами.

Методы REST

REST API позволяет работать с бакетами и объектами через HTTP-запросы.

HTTP-метод	Субъект	Описание
`GET`	`SERVICE`	Получение списка всех бакетов пользователя.
`GET`	`BUCKET`	Получение списка объектов в бакете.
`PUT`	`BUCKET`	Создание нового бакета.
`DELETE`	`BUCKET`	Удаление бакета.
`HEAD`	`BUCKET`	Получение метаданных бакета.
`PUT`	`OBJECT`	Загрузка объекта в бакет.
`POST`	`OBJECT`	Загрузка объекта через HTML-форму.
`GET`	`OBJECT`	Скачивание объекта из бакета.
`DELETE`	`OBJECT`	Удаление объекта.
`HEAD`	`OBJECT`	Получение метаданных объекта.
`PUT`	`OBJECT_COPY`	Создание копии объекта внутри бакета.
`GET`	`OBJECT_ACL`	Получение списка управления доступом (ACL) для объекта.
`PUT`	`OBJECT_ACL`	Установка ACL для объекта.
`PUT`	`BUCKET_ACL`	Загрузка списка управления доступом для бакета.
`GET`	`BUCKET_ACL`	Получение ACL бакета.
`PUT`	`BUCKET_LIFECYCLE`	Настройка правил жизненного цикла объектов.
`GET`	`BUCKET_LIFECYCLE`	Получение правил жизненного цикла.
`DELETE`	`BUCKET_LIFECYCLE`	Удаление правил жизненного цикла объектов.
`PUT`	`BUCKET_CORS`	Настройка CORS для бакета.
`GET`	`BUCKET_CORS`	Получение конфигурации CORS.
`DELETE`	`BUCKET_CORS`	Удаление конфигурации CORS.
`PUT`	`BUCKETPOLICY`	Применение политики доступа к бакету.
`GET`	`BUCKETPOLICY`	Получение политики доступа бакета.
`DELETE`	`BUCKETPOLICY`	Удаление политики доступа бакета.
`PUT`	`BUCKET_TAGGING`	Назначение меток бакету.
`GET`	`BUCKET_TAGGING`	Получение меток бакета.
`DELETE`	`BUCKET_TAGGING`	Удаление меток бакета.
`GET`	`MULTIPART`	Получение списка составных загрузок.
`POST`	`INIT_MULTIPART`	Инициализация составной загрузки.
`POST`	`COMPLETE_MULTIPART`	Завершение составной загрузки.
`DELETE`	`ABORT_MULTIPART`	Прерывание составной загрузки и удаление частей.
`PUT`	`UPLOAD_PART`	Загрузка части объекта.
`PUT`	`UPLOAD_PART_COPY`	Копирование части объекта.
`GET`	`UPLOAD_PART`	Получение списка загруженных частей.

Методы gRPC

gRPC использует удаленные вызовы процедур через HTTP/2 и Protobuf. Вместо стандартных HTTP-методов здесь есть операции с четко определенными сервисами и сообщениями.

Операция gRPC	Пояснение
`CreateBucket(CreateBucketRequest)`	Создает новый бакет.
`DeleteBucket(DeleteBucketRequest)`	Удаляет бакет.
`ListBuckets(ListBucketsRequest)`	Возвращает список всех бакетов пользователя.
`GetBucketMetadata(GetBucketMetadataRequest)`	Получение метаданных бакета.
`PutObject(PutObjectRequest)`	Загрузка объекта в бакет.
`GetObject(GetObjectRequest)`	Получение объекта.
`DeleteObject(DeleteObjectRequest)`	Удаление объекта.
`CopyObject(CopyObjectRequest)`	Копирование объекта внутри бакета.
`ListObjects(ListObjectsRequest)`	Получение списка объектов в бакете.
`GetObjectACL(GetObjectACLRequest)`	Получение списка управления доступом (ACL) объекта.
`PutObjectACL(PutObjectACLRequest)`	Установка ACL для объекта.
`ListMultipartUploads(ListMultipartUploadsRequest)`	Получение списка составных загрузок.
`InitMultipartUpload(InitMultipartUploadRequest)`	Инициализация составной загрузки.
`UploadPart(UploadPartRequest)`	Загрузка части объекта.
`CompleteMultipartUpload(CompleteMultipartUploadRequest)`	Завершение составной загрузки.
`AbortMultipartUpload(AbortMultipartUploadRequest)`	Прерывание составной загрузки.

Примечание: gRPC использует бинарные сообщения и стриминг, что позволяет передавать большие объемы данных быстрее, чем REST.

REST, совместимый с AWS S3

REST API, совместимый облачным хранилищем файлов AWS S3, поддерживает стандартные операции на бакетах и объектах. Это позволяет клиентам, рассчитанным на AWS S3, работать с вашим хранилищем без изменений.

Особенности совместимого REST

Поддержка всех стандартных операций Amazon S3;
Использование заголовков AWS для подписи запросов (Authorization, x-amz-date, x-amz-content-sha256);
Совместимость с клиентскими SDK AWS;
Поддержка версионирования объектов и классов хранения;
Возможность использовать pre-signed URL.

Основные методы

HTTP-метод	Субъект	Описание
`GET`	`SERVICE`	Список всех доступных бакетов.
`GET`	`BUCKET`	Получение списка объектов в бакете.
`PUT`	`BUCKET`	Создание бакета.
`DELETE`	`BUCKET`	Удаление бакета.
`HEAD`	`BUCKET`	Получение метаданных бакета.
`PUT`	`OBJECT`	Загрузка объекта.
`GET`	`OBJECT`	Получение объекта.
`DELETE`	`OBJECT`	Удаление объекта.
`HEAD`	`OBJECT`	Получение метаданных объекта.
`PUT`	`OBJECT_COPY`	Копирование объекта.
`GET`	`OBJECT_ACL`	Получение списка управления доступом для объекта.
`PUT`	`OBJECT_ACL`	Установка ACL для объекта.

Основные типы аутентификации​

Механизм проверки подписи​

Примеры запросов аутентификации​

Пример GET-запроса (через curl)​

Пример pre-signed URL​

Пример GET-запроса получения объекта для AWS S3 (через curl)​

Пример pre-signed URL для AWS S3 (Python)​

gRPC и REST для работы с объектным хранилищем​

gRPC​

REST​

Когда что использовать?​

Методы REST​

Методы gRPC​

REST, совместимый с AWS S3​

Особенности совместимого REST​

Основные методы​