Trabajo con S3 en Node.js: biblioteca @aws-sdk/client-s3 |…

Biblioteca @aws-sdk/client-s3 para trabajar con S3 y almacenamiento en la nube en Node.js

Los almacenamientos en la nube se han convertido en una parte esencial de las aplicaciones web modernas. Permiten almacenar y transferir archivos de cualquier tamaño, garantizando alta disponibilidad y escalabilidad. En el ecosistema de JavaScript (Node.js), una de las bibliotecas más populares para trabajar con almacenamientos compatibles con S3 es @aws-sdk/client-s3 — el SDK oficial de AWS de tercera generación.

Esta biblioteca proporciona un conjunto completo de métodos para interactuar con Amazon S3, así como con cualquier almacenamiento de objetos compatible con S3 (por ejemplo, MinIO, DigitalOcean Spaces, Yandex Object Storage, VK Cloud). En este artículo, analizaremos la instalación, configuración y las operaciones principales: carga, descarga, eliminación y obtención de la lista de objetos.

Instalación y configuración

Para comenzar, instale el paquete a través de npm:

npm install @aws-sdk/client-s3

Después de la instalación, importe las clases necesarias en su proyecto:

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

Configuración del cliente S3

Para conectarse a S3, debe crear una instancia del cliente, especificando la región, las claves de acceso y, si es necesario, el endpoint (para almacenamientos de terceros).

const s3Client = new S3Client({  region: 'ru-central1', // región de su almacenamiento  endpoint: 'https://storage.yandexcloud.net', // para Yandex Object Storage  credentials: {    accessKeyId: 'YOUR_ACCESS_KEY',    secretAccessKey: 'YOUR_SECRET_KEY'  }});

Si utiliza Amazon S3 directamente, no es necesario especificar el endpoint — el SDK lo determinará automáticamente según la región. Para pruebas locales con MinIO, especifique endpoint: 'http://localhost:9000' y forcePathStyle: true.

Operaciones principales con S3

1. Carga de archivo (PutObject)

Para cargar un archivo en un bucket, use el comando PutObjectCommand. Los datos se pueden pasar como cadena, buffer o flujo.

const uploadFile = async (bucketName, key, body) => {  try {    const command = new PutObjectCommand({      Bucket: bucketName,      Key: key,      Body: body,      ContentType: 'text/plain' // opcional    });    const response = await s3Client.send(command);    console.log('Archivo cargado:', response);  } catch (err) {    console.error('Error al cargar:', err);  }};

// Ejemplo de usouploadFile('my-bucket', 'hello.txt', '¡Hola, mundo!');

2. Descarga de archivo (GetObject)

Para obtener un objeto del almacenamiento, se usa GetObjectCommand. Los datos se devuelven como un flujo que se puede convertir a cadena o buffer.

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('Contenido del archivo:', str);    return str;  } catch (err) {    console.error('Error al descargar:', err);  }};

// Ejemplo de usodownloadFile('my-bucket', 'hello.txt');

3. Eliminación de archivo (DeleteObject)

La eliminación de un objeto se realiza con el comando DeleteObjectCommand.

const deleteFile = async (bucketName, key) => {  try {    const command = new DeleteObjectCommand({      Bucket: bucketName,      Key: key    });    await s3Client.send(command);    console.log('Archivo eliminado');  } catch (err) {    console.error('Error al eliminar:', err);  }};

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