Blob Storage: ¿qué es y cómo usarlo?

En el desarrollo de aplicaciones modernas, gestionar archivos (imágenes, vídeos, documentos) directamente en el servidor de la aplicación puede consumir recursos preciosos y complicar el escalamiento. El Blob Storage de Square Cloud resuelve este problema ofreciendo un almacenamiento de objetos binarios (Binary Large Objects) totalmente serverless, con baja latencia y CDN incluida.

1. ¿Qué es y por qué usarlo?

El Blob Storage es un servicio de almacenamiento de activos diseñado para alta disponibilidad. A diferencia de un sistema de archivos tradicional, está optimizado para lectura rápida a través de una Red de Entrega de Contenido (CDN).

• Serverless: No necesitas gestionar discos ni volúmenes.
• Baja latencia: Gracias a la CDN, el contenido se sirve desde el punto de presencia más cercano al usuario.
• Eficiencia: Reduce la carga de I/O del servidor principal de tu aplicación o bot.

2. Control sobre los activos

Al subir un archivo al Blob, tienes control total sobre el comportamiento del activo:

• Expiración: Define un tiempo de vida para el archivo (ideal para archivos temporales).
• Nombre y prefijo: Organiza tus archivos en "carpetas" lógicas usando prefijos.
• Hash de seguridad: Genera un sufijo aleatorio para evitar que el enlace sea "adivinado" por terceros.
• Descarga automática: Opción para forzar al navegador a descargar el archivo en lugar de solo visualizarlo.

3. Límites y formatos soportados

El servicio permite el envío de archivos entre 512 B y 10 GiB: hasta 100 MB en una sola solicitud y, por encima de eso, hasta 10 GiB con la carga en partes. Se acepta prácticamente cualquier tipo de archivo, incluidos formatos sin tipo MIME registrado: .bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy, etc. La extensión almacenada proviene del nombre de archivo que subes, y los sufijos de compresión compuestos se conservan (reads.fastq.gz se mantiene como .fastq.gz).
La única excepción es una lista de exclusión de ejecutables e instaladores (.exe, .msi, .bat, .apk y similares), rechazados con BLOCKED_FILE_TYPE.

Tienes una cuota gratuita de uso según tu plan. Consulta la tabla de abajo:

4. Estructura de la URL de acceso

Un archivo público queda disponible a través de una URL estandarizada. Lo recomendable es usar el campo url que devuelve la API. La estructura sigue este formato:

https://blob.squarecloud.dev/pub/{id_cuenta}/{prefijo}/{nombre}{_hash}.{ext}

Ejemplo práctico: si tu ID es 123, el prefijo es banners, el archivo es promocion y tiene un hash:

https://blob.squarecloud.dev/pub/123/banners/promocion_xyz789.jpg

Solo los archivos legados siguen en public-blob⁠.squarecloud⁠.dev (hasta el 25/10/2026). Con private=true el archivo queda sin URL pública y se accede por enlace de compartir, descarga temporal o gateway S3.

5. Cómo enviar archivos

Existen dos formas principales de interactuar con el Blob Storage:

Vía Dashboard

Ideal para la gestión manual. Solo accede a la pestaña Blob en tu panel, haz clic en Subir archivos o arrastra los archivos.

Vía API Pública

Para automatización, utiliza el endpoint de POST.

Opción 1: Carga Directa (512B a 100MB)

Recomendado para el flujo estándar de archivos pequeños y medianos.

1. Información General

• Endpoint: https://blob.squarecloud.app/v1/objects
• Método: POST
• Autenticación: Clave de API en el Header.
• Rate Limit: Hobby y Standard: 1 subida por segundo. Pro y Enterprise: sin ese límite. Todas las cuentas: hasta 4 subidas simultáneas.

2. Parámetros de URL (Query Params)

Debes incluir las configuraciones del archivo directamente en la URL de la solicitud:

3. Cabeceras (Headers)

4. Cuerpo de la Solicitud (Body)

El cuerpo debe utilizar el formato FormData conteniendo únicamente el archivo:

• Key: file
• Value: [Archivo Binario]
• mimetype: mimetype del archivo (Ej.: image/jpeg)

Opción 2: Carga en Partes / Chunked (Más de 100MB hasta 10GiB)

Para archivos pesados, el envío se divide en pequeños bloques (chunks). Como no hay estado de sesión guardado en el servidor, todo el proceso depende de un único "token" generado al principio. El flujo consta de hasta cuatro etapas:

1. Iniciar la Carga

Reserva la clave del objeto y abre la transferencia.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: POST
• Parámetros de URL (Query Params): Utiliza los mismos parámetros de la Opción 1 (name, prefix, expire, etc.), con la adición de filename (el nombre y extensión originales, ej.: reads.fastq.gz). Como no hay FormData, la extensión se deriva de filename.
• Respuesta: La API devolverá un token en la propiedad response.upload. Conserva este token, ya que se utilizará en todos los pasos siguientes.

2. Enviar las Partes

Envía los datos del archivo en pedazos. Cada parte (excepto la última) debe tener entre 5MB y 32MB. Puedes enviar hasta 6 partes en paralelo.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: PUT
• Rate Limit: 60 partes cada 10 segundos.
• Parámetros de URL: ?upload=TU_TOKEN_AQUÍ&part=1 (el número part va del 1 al 2048).
• Cabeceras:
• Authorization: TU_CLAVE_API
• Content-Type: application/octet-stream
• Cuerpo (Body): Solo los bytes en bruto (Raw Bytes) del chunk. No utilices multipart/form-data.

3. Concluir la Carga

Después de enviar todas las partes, debes "sellar" el archivo para que la plataforma una las piezas y libere tu URL pública.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: PATCH
• Rate Limit: 5 solicitudes cada 10 segundos.
• Cabeceras:
• Authorization: TU_CLAVE_API
• Content-Type: application/json
• Cuerpo (JSON):

{
  "upload": "TU_TOKEN_AQUÍ"
}

4. Cancelar la Carga (Gestión de Errores)

Si la carga falla o el usuario la abandona, cancélala para limpiar los chunks guardados y liberar espacio dentro del límite de tu cuenta (máximo de 32 cargas abiertas por cuenta, incluido el gateway S3: TOO_MANY_OPEN_UPLOADS).

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: DELETE
• Rate Limit: 10 solicitudes cada 10 segundos.
• Cabeceras:
• Authorization: TU_CLAVE_API
• Content-Type: application/json
• Cuerpo (JSON):

{
  "upload": "TU_TOKEN_AQUÍ"
}

Consejo: Al enviar un archivo sin hash y sin tiempo de expiración, puedes actualizarlo enviando otro archivo del mismo tipo y con los mismos parámetros (prefix/nombre). Recuerda que hay un tiempo de caché por ser una CDN.

6. Buenas prácticas

• Organización: Usa siempre prefijos (ej.: profiles/, logs/) para evitar que la raíz de tu Blob quede desordenada.
• Caché y CDN: Recuerda que los activos en CDN se cachean. Si necesitas actualizar un archivo manteniendo el nombre, el uso de hashes de seguridad es altamente recomendado para evitar que el usuario vea la versión antigua.
• Seguridad: Los archivos públicos son accesibles para cualquiera que tenga el enlace. Para información confidencial, usa private=true y comparte por enlace de compartir o descarga temporal.

Actualizado el: 04/10/2026