Guía para conectar IBM Cloud Object Storage a aplicaciones Node.js

En la era del big data y la alta disponibilidad, contar con una solución de almacenamiento escalable y segura resulta fundamental. IBM Cloud Object Storage (COS) es una opción robusta para almacenar y recuperar datos de forma ágil desde aplicaciones Node.js. En este artículo exploraremos, paso a paso, cómo integrar COS en un proyecto Node.js, configuraciones recomendadas, ejemplos de código detallados y buenas prácticas.

1. ¿Qué es IBM Cloud Object Storage

IBM Cloud Object Storage es un servicio de almacenamiento de objetos diseñado para gestionar grandes volúmenes de datos no estructurados. Sus principales características son:

Escalabilidad automática: Ajusta capacidad según demanda.
Alta durabilidad: Replicación y distribución global.
Seguridad integrada: Cifrado en reposo y en tránsito.
Acceso flexible: API S3 compatible, SDKs y CLI.

2. Casos de uso típicos

Almacenamiento de archivos multimedia (imágenes, video, audio).
Backups y snapshots de bases de datos.
Data lakes y análisis de big data.
Distribución de contenido estático a través de CDN.

3. Requisitos previos

Antes de comenzar, verifica que cuentas con:

Cuenta en IBM Cloud activa. Regístrate en cloud.ibm.com.
Instalación de Node.js (versión recomendada: >=14.x).
Instalación de npm o yarn para gestionar paquetes.
Permisos suficientes para crear credenciales y buckets en IBM COS.

4. Creación de credenciales y bucket

Inicia sesión en IBM Cloud y accede al servicio Cloud Object Storage.
Crea una instancia de servicio: selecciona plan gratuito o de pago según tus necesidades.
En Service credentials, haz clic en Create y asigna un nombre.
Descarga el archivo JSON con las credenciales o copia los campos: apikey, resource_instance_id, endpoint.
En la sección Buckets, haz clic en Create bucket y define un nombre único, la región y las políticas de redundancia.

5. Configuración del proyecto Node.js

En tu terminal, crea un nuevo directorio y ejecuta:

mkdir mi-app-cos
cd mi-app-cos
npm init -y
npm install ibm-cos-sdk dotenv

El paquete ibm-cos-sdk es la librería oficial de IBM para interactuar con COS. Usaremos dotenv para gestionar variables de entorno.

6. Variables de entorno

Crea un archivo .env en la raíz con el siguiente contenido:

IBMCOS_APIKEY=TU_API_KEY
IBMCOS_INSTANCE_ID=TU_RESOURCE_INSTANCE_ID
IBMCOS_ENDPOINT=https://s3.us-south.cloud-object-storage.appdomain.cloud
BUCKET_NAME=nombre-de-tu-bucket

Estos valores los obtuviste al crear las credenciales y el bucket.

7. Inicialización del cliente IBM COS

Crea un archivo cosClient.js con el siguiente código:

require(dotenv).config()
const IBM = require(ibm-cos-sdk)

const config = {
  endpoint: process.env.IBMCOS_ENDPOINT,
  apiKeyId: process.env.IBMCOS_APIKEY,
  ibmAuthEndpoint: https://iam.cloud.ibm.com/identity/token,
  serviceInstanceId: process.env.IBMCOS_INSTANCE_ID
}

const cos = new IBM.S3(config)

module.exports = cos

Este módulo carga las variables de entorno y crea un cliente S3 compatible con IBM COS.

8. Operaciones básicas

8.1 Subir un archivo

const cos = require(./cosClient)
const fs = require(fs)
const path = require(path)

async function uploadFile(keyName, filePath) {
  try {
    const fileStream = fs.createReadStream(filePath)
    const params = {
      Bucket: process.env.BUCKET_NAME,
      Key: keyName,
      Body: fileStream,
      ACL: private
    }
    const data = await cos.upload(params).promise()
    console.log(Archivo subido con éxito:, data.Location)
  } catch (err) {
    console.error(Error al subir archivo:, err)
  }
}

// Uso
uploadFile(imagen.jpg, path.join(__dirname, recursos/imagen.jpg))

8.2 Listar objetos

async function listObjects() {
  try {
    const params = { Bucket: process.env.BUCKET_NAME }
    const data = await cos.listObjects(params).promise()
    console.log(Objetos en el bucket:)
    data.Contents.forEach(obj => console.log(-, obj.Key))
  } catch (err) {
    console.error(Error al listar objetos:, err)
  }
}

// Uso
listObjects()

8.3 Descargar un archivo

async function downloadFile(keyName, downloadPath) {
  try {
    const params = {
      Bucket: process.env.BUCKET_NAME,
      Key: keyName
    }
    const data = await cos.getObject(params).promise()
    fs.writeFileSync(downloadPath, data.Body)
    console.log(Archivo descargado en:, downloadPath)
  } catch (err) {
    console.error(Error al descargar archivo:, err)
  }
}

// Uso
downloadFile(imagen.jpg, path.join(__dirname, descargas/imagen.jpg))

8.4 Eliminar un objeto

async function deleteObject(keyName) {
  try {
    const params = {
      Bucket: process.env.BUCKET_NAME,
      Key: keyName
    }
    await cos.deleteObject(params).promise()
    console.log(Objeto eliminado:, keyName)
  } catch (err) {
    console.error(Error al eliminar objeto:, err)
  }
}

// Uso
deleteObject(imagen.jpg)

9. Manejo de errores y buenas prácticas

Reintentos con exponencial backoff: Configure la propiedad maxRetries y retryDelayOptions en el cliente.
Validación de parámetros: Asegúrese de validar Key, Bucket y archivos antes de las operaciones.
Seguridad: Use IAM roles y políticas para limitar el acceso. Evite exponer API keys en el código fuente público.
Logs y monitoreo: Integre con IBM Log Analysis o soluciones externas.

10. Operaciones avanzadas

10.1 Subidas múltiples en partes (multipart upload)

Útil para archivos de gran tamaño (>100 MB). Permite dividir en partes y subir en paralelo:

async function multipartUpload(keyName, filePath) {
  const fileStream = fs.createReadStream(filePath)
  const params = {
    Bucket: process.env.BUCKET_NAME,
    Key: keyName,
    Body: fileStream,
    PartSize: 10  1024  1024, // 10 MB
    QueueSize: 4
  }
  try {
    const data = await cos.upload(params).promise()
    console.log(Subida multipart completada en:, data.Location)
  } catch (err) {
    console.error(Error en multipart upload:, err)
  }
}

10.2 Presigned URLs

Genera URLs temporales para compartir archivos sin exponer credenciales:

async function generatePresignedUrl(keyName, expiresInSeconds = 300) {
  try {
    const params = {
      Bucket: process.env.BUCKET_NAME,
      Key: keyName,
      Expires: expiresInSeconds
    }
    const url = await cos.getSignedUrlPromise(getObject, params)
    return url
  } catch (err) {
    console.error(Error al generar presigned URL:, err)
  }
}

11. Tabla de configuración de cliente

Opción	Descripción	Valor por defecto
endpoint	URL del endpoint IBM COS	—
apiKeyId	API Key para autenticación	—
serviceInstanceId	ID de la instancia del servicio	—
maxRetries	Número máximo de reintentos	3
sslEnabled	Forzar uso de TLS/SSL	true

12. Conclusiones

Integrar IBM Cloud Object Storage con Node.js te permite construir aplicaciones con alta disponibilidad, escalables y seguras. Hemos cubierto desde la creación de credenciales y buckets, hasta ejemplos de código para las operaciones más comunes y avanzadas. No olvides implementar prácticas de seguridad, monitoreo y optimización de rendimiento para maximizar la eficiencia de tu plataforma.

SushiHost

Guía para conectar IBM Cloud Object Storage a aplicaciones Node.js