Работа с S3 и облачными хранилищами в JavaScript (Node.js) — библиотека @aws-sdk/client-s3

Библиотека @aws-sdk/client-s3 для работы с S3 и облачными хранилищами в Node.js

Облачные хранилища стали неотъемлемой частью современных веб-приложений. Они позволяют хранить и передавать файлы любого размера, обеспечивая высокую доступность и масштабируемость. В экосистеме JavaScript (Node.js) одной из самых популярных библиотек для работы с S3-совместимыми хранилищами является @aws-sdk/client-s3 — официальный AWS SDK третьего поколения.

Эта библиотека предоставляет полный набор методов для взаимодействия с Amazon S3, а также с любыми S3-совместимыми объектными хранилищами (например, MinIO, DigitalOcean Spaces, Yandex Object Storage, VK Cloud). В этой статье мы разберём установку, настройку и основные операции: загрузку, скачивание, удаление и получение списка объектов.

Установка и подключение

Для начала работы установите пакет через npm:

npm install @aws-sdk/client-s3

После установки импортируйте необходимые классы в ваш проект:

const { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, ListObjectsV2Command } = require('@aws-sdk/client-s3');

Настройка клиента S3

Для подключения к S3 необходимо создать экземпляр клиента, указав регион, ключи доступа и, при необходимости, эндпоинт (для сторонних хранилищ).

const s3Client = new S3Client({
  region: 'ru-central1', // регион вашего хранилища
  endpoint: 'https://storage.yandexcloud.net', // для Yandex Object Storage
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY'
  }
});

Если вы используете Amazon S3 напрямую, эндпоинт указывать не обязательно — SDK определит его автоматически по региону. Для локального тестирования с MinIO укажите endpoint: 'http://localhost:9000' и forcePathStyle: true.

Основные операции с S3

1. Загрузка файла (PutObject)

Чтобы загрузить файл в бакет, используйте команду PutObjectCommand. Данные можно передавать как строку, буфер или поток.

const uploadFile = async (bucketName, key, body) => {
  try {
    const command = new PutObjectCommand({
      Bucket: bucketName,
      Key: key,
      Body: body,
      ContentType: 'text/plain' // опционально
    });
    const response = await s3Client.send(command);
    console.log('Файл загружен:', response);
  } catch (err) {
    console.error('Ошибка загрузки:', err);
  }
};

// Пример использования
uploadFile('my-bucket', 'hello.txt', 'Привет, мир!');

2. Скачивание файла (GetObject)

Для получения объекта из хранилища используется GetObjectCommand. Данные возвращаются в виде потока, который можно преобразовать в строку или буфер.

const downloadFile = async (bucketName, key) => {
  try {
    const command = new GetObjectCommand({
      Bucket: bucketName,
      Key: key
    });
    const response = await s3Client.send(command);
    const str = await response.Body.transformToString('utf-8');
    console.log('Содержимое файла:', str);
    return str;
  } catch (err) {
    console.error('Ошибка скачивания:', err);
  }
};

// Пример использования
downloadFile('my-bucket', 'hello.txt');

3. Удаление файла (DeleteObject)

Удаление объекта выполняется командой DeleteObjectCommand.

const deleteFile = async (bucketName, key) => {
  try {
    const command = new DeleteObjectCommand({
      Bucket: bucketName,
      Key: key
    });
    await s3Client.send(command);
    console.log('Файл удалён');
  } catch (err) {
    console.error('Ошибка удаления:', err);
  }
};

deleteFile('my-bucket', 'hello.txt');

4. Получение списка объектов (ListObjectsV2)

Для перечисления всех объектов в бакете используется ListObjectsV2Command. Результат содержит массив объектов с метаданными.

const listFiles = async (bucketName) => {
  try {
    const command = new ListObjectsV2Command({
      Bucket: bucketName
    });
    const response = await s3Client.send(command);
    if (response.Contents) {
      response.Contents.forEach(obj => {
        console.log(`- ${obj.Key} (${obj.Size} байт)`);
      });
    } else {
      console.log('Бакет пуст');
    }
  } catch (err) {
    console.error('Ошибка получения списка:', err);
  }
};

listFiles('my-bucket');

Работа с S3-совме