При разработке веб-приложений в первую очередь нужно решить, где будут храниться файлы, с которыми работает приложение. В традиционных веб-приложениях файлы обычно размещаются на сервере, который обслуживает приложение. Однако этот метод имеет свои ограничения: сложно эффективно управлять большим количеством данных и обеспечить их безопасность. Более современным и удобным решением является использование облачного хранилища, которое позволяет легко сохранять и получать файлы через интернет. Одним из вариантов облачного хранилища является объектное хранилище S3.
Объектное хранилище — это тип хранения данных, где информация сохраняется как отдельные объекты, что позволяет эффективно управлять большими объемами данных. В нашем случае объекты — это файлы, которые мы будем загружать и скачивать с облака. В этой статье мы покажем, как настроить S3-хранилище Timeweb Cloud и подключить его к вашему веб-приложению.
Наш проект разрабатывается на .NET 9 — одной из самых последних версий фреймворка от Microsoft. Эта платформа обеспечивает высокую производительность веб-приложений, особенно при использовании ASP.NET, что позволяет эффективно обрабатывать пользовательские запросы через интернет.
В этой статье мы рассмотрим следующие ключевые этапы настройки нашего проекта:
-
Создание проекта в Timeweb Cloud — создадим проект и объектное хранилище в Timeweb Cloud и настроим его для хранения наших файлов.
-
Развертывание ASP.NET-проекта — создадим веб-приложение на ASP.NET и подготовим его для работы, настроив все необходимые компоненты для обработки запросов.
-
Установка необходимых NuGet-пакетов — NuGet — это система для управления библиотеками и пакетами в .NET. Мы подключим библиотеки, которые помогут работать с S3-хранилищем, чтобы мы могли загружать и скачивать файлы.
-
Добавление поддержки Scalar — подключим поддержку OpenAPI с помощью Scalar, чтобы упростить тестирование нашего API (интерфейса для взаимодействия с приложением).
-
Настройка переменных окружения — для надежного хранения ключей доступа к S3-хранилищу настроим переменные окружения, чтобы хранить конфиденциальную информацию в безопасном месте, а не прямо в коде.
-
Создание минимального Docker-контейнера — Docker — это инструмент, который позволяет упаковать приложение в контейнер, что упрощает его развертывание на разных серверах. Мы создадим контейнер, чтобы проще развернуть наше приложение в облаке.
-
Подключение к S3 API — научимся работать с S3 API, чтобы загружать и скачивать файлы.
-
Разработка контроллеров — добавим эндпоинты (адреса, по которым приложение будет получать запросы) для работы с хранилищем, чтобы пользователи могли загружать и скачивать файлы через интернет.
Весь процесс будет пошаговым, и в конце вы получите работающий API, который будет взаимодействовать с облачным хранилищем S3, позволяя загружать и скачивать файлы.
Объектное S3-хранилище
совместимое с протоколом Amazon S3.
Шаг 1. Создание проекта в Timeweb Cloud
-
Перейдите в панель управления Timeweb Cloud и создайте новый проект.
-
В панели управления создайте S3-хранилище. Выберите подходящий тариф (для тестового развертывания достаточно минимального конфигурации) и перейдите в бакет — контейнер для хранения объектов.
- Перейдите в сам бакет, чтобы просмотреть его конфигурацию. Он будет доступен внутри вашего проекта или в разделе «Хранилище S3».
-
Сохраните три ключевых значения:
-
- Название бакета
- S3 Access Key
- S3 Secret Access Key
Шаг 2. Развертывание ASP.NET-проекта
Выполнение этого и следующих шагов также представлено на скринкасте.
Откройте консоль и создайте директорию для проекта:
Затем перейдите в эту директорию:
Инициализируйте проект командой:
Проект будет создан с версией .NET 9. Чтобы убедиться в этом, откройте файл с расширением .csproj и найдите строку:
Для минимальной конфигурации файл Program.cs должен выглядеть так:
Шаг 3. Установка NuGet-пакетов
Для работы с S3 и нужными библиотеками установите необходимые пакеты, поочередно выполнив следующие команды:
После установки пакетов дождитесь их загрузки и подтвердите установку последнего пакета, снова нажав Enter.
Затем соберите проект, выполнив команду:
Шаг 4. Добавление файла GlobalUsings.cs
Создайте файл GlobalUsings.cs в корне проекта и добавьте в него следующие пространства имен:
Этот файл позволит избежать дублирования директив using в каждом файле проекта, обеспечивая доступ к необходимым библиотекам везде, где это потребуется.
Шаг 5. Добавление Scalar для поддержки API
Добавьте поддержку Scalar API, чтобы упростить тестирование приложения.
Для этого откройте Program.cs и сразу после строки var app = builder.Build(); добавьте:
Это создаст страницу http://localhost/scalar, где веб-клиент сможет видеть доступные API-эндпоинты — адреса, по которым можно отправлять запросы.
Шаг 6. Настройка переменных окружения
Создайте файл .env в корневой папке проекта. В этом файле будут храниться переменные окружения — настройки, которые приложение будет использовать при работе.
Замените значения в скобках на свои данные для подключения к бакету.
Пример содержимого файла:
В итоге файл будет выглядеть подобным образом:
Добавьте в проект переменные окружения. Для этого откройте Program.cs и вставьте следующий код сразу после строки var builder = WebApplication.CreateBuilder(args):
Шаг 7. Создание Docker-контейнера
Создайте Dockerfile в корневой папке проекта. Этот файл нужен, чтобы Docker мог собрать образ — упакованную версию приложения со всеми зависимостями, готовую для запуска в любой среде.
Добавьте файл docker-compose.yml со следующим содержимым:
Шаг 8. Подключение к S3 API
Создайте файл S3Options.cs в корневой папке проекта. В нем будут храниться настройки для подключения к S3-хранилищу. Добавьте в него следующий код:
Далее для того, чтобы использовать настройки окружения в нашем приложении, в файл Program.cs после строки builder.Services.AddOpenApi(); добавьте код:
Он нужен, чтобы передать настройки для работы с S3-хранилищем (например, ключи доступа и адрес сервиса) и сделать их доступными в приложении. Это называется «внедрение зависимостей» — способ передавать нужные параметры в разные части кода без их явного указания в каждом месте.
Шаг 9. Разработка контроллеров для работы с S3 в .NET 9
Для работы с объектным хранилищем S3 от Timeweb Cloud в проекте необходимо создать контроллер S3Controller. Он будет обрабатывать загрузку, получение и удаление изображений в S3.
Создание контроллера
В корневой директории создаем папку Controllers, а в ней — файл S3Controller.cs. Добавьте в него следующий код:
Контроллер помечается атрибутами:
-
[ApiController]— указывает, что этот класс является контроллером API. -
[Route("api/s3")]— задает маршрут для запросов, начинающихся сapi/s3.
Также контроллер использует зависимости:
-
S3Options— объект конфигурации с настройками доступа к S3. -
IAmazonS3— клиент для взаимодействия с S3.
Они передаются через конструктор с внедрением зависимостей (IOptions<S3Options> для конфигурации и IAmazonS3 для работы с S3).
Разберем методы работы с файлами:
Метод [HttpPost("image/{id}")] используется для загрузки изображения в S3.
При вызове метода создается запрос PutObjectRequest, в котором указываются:
id— идентификатор файла (например, ID объекта в базе данных).IFormFile file— полученный файл изmultipart/form-data.
Входные параметры метода:
BucketName— название бакета,Key— имя файла в S3 (в данном случае переданный id),ContentType— тип файла,InputStream— поток загружаемого файла.
Запрос передается в PutObjectAsync, который выполняет загрузку. Если ответ OK (200), загрузка прошла успешно, иначе возвращается ошибка.
Метод [HttpGet("image/{id}")] позволяет получить изображение из S3.
При вызове метода создается запрос GetObjectRequest, в котором указываются:
BucketName— название бакета,Key— идентификатор файла.
Входной параметр метода:
id— идентификатор файла в S3.
Метод [HttpDelete("image/{id}")] удаляет изображение из S3.
При вызове метода создается запрос DeleteObjectRequest, содержащий:
BucketName— название бакета,Key— идентификатор файла.
Входной параметр метода:
id— идентификатор файла в S3.
После этого выполняется DeleteObjectAsync. Если статус ответа NoContent (204), файл успешно удален, иначе возвращается ошибка.
Добавление маршрутов в приложение
Чтобы контроллер начал работать, необходимо добавить в файле Program.cs после app.MapOpenApi(); следующие строки:
Этот метод регистрирует маршруты для всех контроллеров в приложении, включая S3Controller.
Также перед строкой var app = builder.Build(); добавьте:
Вызов функции сообщает ASP.NET Core, что в приложении будут использоваться контроллеры и их нужно зарегистрировать. Без этого контроллеры не будут работать, даже если маршруты настроены.
Шаг 10. Тестирование с помощью Docker и Postman
Для тестирования нашего API, которое теперь доступно по адресу http://localhost, мы будем использовать два инструмента: Postman и Scalar. В обоих случаях мы будем отправлять HTTP-запросы на следующие эндпоинты:
- GET для получения файла по ID
- POST для загрузки файла
- DELETE для удаления файла
Эти запросы будут выполняться по шаблону http://localhost/api/s3/image/{id}, где {id} — это уникальный идентификатор изображения, с которым мы будем взаимодействовать.
Сначала необходимо запустить контейнер, чтобы приложение стало доступно. Для этого в терминале, находясь в директории проекта, выполните команду:
Это создаст и запустит Docker-контейнер, собрав все необходимые компоненты приложения.
Тестирование с помощью Postman
Postman — это инструмент для тестирования API. Мы будем использовать его для отправки запросов на наш сервер.
Откройте Postman и введите URL запроса в формате http://localhost/api/s3/image/{id}, где {id} — это значение, которое вы хотите использовать для тестирования (например, 1).
Убедитесь, что запрос использует правильный HTTP-метод (GET, POST или DELETE).
Пример GET-запроса
URL: http://localhost/api/s3/image/1
Этот запрос будет пытаться получить файл с ID 1. Ответ будет содержать файл (если он существует) или сообщение об ошибке.
Пример POST-запроса (Загрузка файла)
URL: http://localhost/api/s3/image/1
В теле запроса:
- Тип данных:
form-data. - Ключ:
Data— сюда нужно добавить файл для загрузки.
Это запрос для загрузки изображения с ID 1 в хранилище S3. В form-data вы должны прикрепить файл, который хотите загрузить.
Пример DELETE-запроса (Удаление файла)
URL: http://localhost/api/s3/image/1
Этот запрос удаляет файл с ID 1 из S3-хранилища.
Пример из Postman продемонстрирован на картинке ниже.
Тестирование с помощью Scalar
Scalar — это инструмент для тестирования API с использованием OpenAPI, который подключен для удобства. Он позволяет увидеть список всех доступных эндпоинтов и взаимодействовать с ними прямо из браузера.
При использовании Scalar выполните следующие действия.
- Откройте браузер и перейдите по адресу:
Здесь отобразится список всех доступных эндпоинтов, включая /api/s3/image/{id} для работы с изображениями.
- В интерфейсе Scalar выберите нужный HTTP-метод (GET, POST или DELETE).
- Настройте запрос. Вы можете задать параметры запроса, например, указать id изображения, и отправить запрос непосредственно из Scalar
Примеры запросов в Scalar:
GET-запрос
URL: http://localhost/api/s3/image/1
Этот запрос пытается получить файл с ID 1. Если файл существует, Scalar вернет его с оригинальным Content-Type, иначе — сообщение об ошибке.
POST-запрос (Загрузка файла)
URL: http://localhost/api/s3/image/1
В теле запроса:
- Тип данных:
form-data - Ключ:
Data— здесь нужно прикрепить файл для загрузки
Этот запрос загружает изображение с ID 1 в хранилище S3.
DELETE-запрос
URL: http://localhost/api/s3/image/1
Этот запрос удаляет файл с ID 1 из S3-хранилища.
Пример из Scalar продемонстрирован на картинке ниже.
Тестирование через Postman и Scalar поможет убедиться, что все эндпоинты работают правильно и файлы могут быть загружены, получены и удалены с S3-хранилища.
Надежное облако для ваших проектов
477 ₽/мес
657 ₽/мес
Заключение
Мы успешно разработали и настроили приложение для работы с файлами в объектном хранилище S3 от Timeweb Cloud: создали хранилище, настроили проект на .NET 9, подключили необходимые библиотеки для работы с S3 и добавили поддержку Scalar. Мы также настроили переменные окружения и создали Docker-контейнер.
Теперь наше приложение позволяет загружать, получать и удалять файлы через API, взаимодействуя с объектным хранилищем S3, что делает его удобным и безопасным для использования в реальных проектах.
