> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Blob Storage: qué es y cómo usarlo (CDN) # 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 **512B y 1GiB**. 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: | Plan | Almacenamiento gratuito incluido | | ---- | | Hobby-1 | **5 GB** | | Hobby-2 | **15 GB** | | Standard-4 | **30 GB** | | Standard-6 | **50 GB** | | Standard-8 | **100 GB** | | Pro-12 | **200 GB** | | Pro-16 | **250 GB** | | Enterprise | **250 GB** | --- ## 4. Estructura de la URL de acceso Una vez que el archivo es enviado, queda disponible públicamente a través de una URL estandarizada. La estructura sigue este formato: https://public-blob.squarecloud.dev/{id_cuenta_square}/{prefijo}/{filename}{_hash_seguridad}{extensión} > **Ejemplo práctico:** > Si tu ID es `123`, el prefijo es `banners`, el archivo es `promocion` y tiene un hash: > https://public-blob.squarecloud.dev/123/banners/promocion_xyz789.jpg > Si optas por no definir prefijo ni hash, sin tiempo de expiración: > https://public-blob.squarecloud.dev/123/promocion.jpg --- ## 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 **Enviar nuevo objeto** y rellena el formulario. ### 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:** 1/s 2. Parámetros de URL (Query Params) Debes incluir las configuraciones del archivo directamente en la URL de la solicitud: | Parámetro | Tipo | Obligatorio | Descripción | | ---- | | `name` | String | Sí | Nombre del archivo (sin extensión). Patrón: `a-zA-Z0-9_` (3-32 caracteres). | | `prefix` | String | No | Carpeta/prefijo para organizar el archivo. | | `expire` | Number | No | Días para la expiración (1 a 365). No definirlo lo hará permanente (hasta que se elimine manualmente). | | `security_hash` | Boolean | No | `true` para exigir un hash de seguridad en el acceso. | | `auto_download` | Boolean | No | `true` para forzar la descarga al abrir la URL. | 3. Cabeceras (Headers) | Clave | Valor | | ---- | | `Authorization` | `TU_CLAVE_API` | 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 1GiB) 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 205). * **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):** ```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 8 cargas abiertas). * **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):** ```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:** Aunque el enlace contiene el ID de tu cuenta, es público. No almacenes información confidencial sin cifrar.