Migra de Filestack a Transloadit

Filestack ofrece selección de archivos, subidas, almacenamiento y transformaciones CDN⁠ y flujos de trabajo asíncronos⁠. Con Transloadit, Uppy se encarga de la selección en el navegador y los Robots se encargan del procesamiento de archivos. Define un flujo de trabajo compatible en un Template y luego usa un SDK, Uppy o la API REST para crear Assemblies. Revisa individualmente las tareas que usa tu aplicación; la correspondencia que se muestra a continuación no promete una paridad de funciones completa.

Esta guía cubre el procesamiento y la exportación de archivos hacia un almacenamiento que tú controlas. No implementa una migración a un DAM alojado de Transloadit. Importar a una Media Library alojada, conservar sus carpetas y metadatos, la entrega mediante tlcdn.com, los simulacros y manifiestos de migración, y los roles, widgets e integraciones de CMS/editor de la Media Library requieren un plan de migración independiente. El inventario descrito a continuación es un registro de migración propiedad de la aplicación, no una herramienta de migración a un DAM alojado.

Mapa de migración

Los alias de almacenamiento de Filestack exponen el almacenamiento externo existente a su servicio de procesamiento sin necesidad de subir a través de Filestack. Si ya eres propietario del bucket de origen, decide si los originales pueden permanecer allí mientras procesas y exportas nuevas derivaciones. Para el almacenamiento gestionado por Filestack, descarga los originales autorizados mediante su CDN⁠ antes de dar de baja la cuenta. Esta guía no ofrece un script de exportación masiva de cuentas ni de descubrimiento de activos.

Conserva el catálogo por separado. Antes de copiar los bytes, registra el ID de activo, el handle de Filestack, la URL de descarga original, la ubicación/contenedor/ruta de almacenamiento, el nombre de archivo, el tipo MIME, el tamaño, el checksum y las derivaciones requeridas. El endpoint de metadatos⁠ de Filestack puede devolver datos del archivo, información de almacenamiento y hashes; genera esa información bajo demanda. Mantén el inventario de origen y la correspondencia de Assembly/exportación completada en tu propia base de datos.

Las etiquetas de subida del Picker⁠ de Filestack se devuelven en las respuestas de subida y en los webhooks. Su DAM⁠ también permite a los usuarios editar las etiquetas y descripciones de los activos. Conserva esos registros por separado de los metadatos del archivo; los Templates que se muestran a continuación copian y procesan bytes, no etiquetas o descripciones de catálogo. Usa las rutas de almacenamiento registradas para decidir cómo las claves de objeto de destino conservan las carpetas; estos ejemplos generan rutas nuevas. Haz un inventario de las colecciones y relaciones de revisión que usa tu aplicación, incluyendo su orden y permisos. La operación de sobrescritura⁠ de Filestack reemplaza el archivo detrás de un handle, por lo que una descarga no es una exportación del historial de versiones. Esta guía no exporta la pertenencia a colecciones ni las revisiones históricas; obtenlas de tu aplicación o de tu archivo existente antes de cambiar si son necesarias.

Crea un Template para cada flujo de trabajo

Traduce las recetas de transformación. El Processing Engine⁠ de Filestack acepta tareas en URL de CDN, mientras que sus flujos de trabajo definen tareas y lógica condicional. Haz un inventario de la cadena completa de tareas, parámetros, ajustes preestablecidos propios de la aplicación, IDs de flujo de trabajo y condiciones usados por cada vista de la aplicación. Reconstruye las recetas necesarias como Templates, genera las derivaciones y compara imágenes y documentos representativos en cuanto a recorte, relación de aspecto, orientación, selección de página, calidad y formato. Un Robot de miniaturas no reemplaza el Filestack Document Viewer⁠ interactivo; elige un visor independiente si tu aplicación lo necesita. Los ejemplos a continuación cubren vistas previas de imágenes/PDF y una vista previa genérica de archivos; no reproducen todas las tareas de transformación o inteligencia de Filestack.

Este Template verifica el tipo MIME detectado, crea una miniatura de imagen o una miniatura de la primera página de un PDF, y almacena los originales aceptados y las vistas previas. Otros tipos MIME detienen la Assembly con un error. Esto es un filtro por tipo, no un escaneo de malware; agrega /file/virusscan si tu flujo de trabajo lo requiere:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^(image/[^/]+|application/pdf)$"]],
      "error_on_decline": true
    },
    "images": {
      "use": "accepted_files",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^image/"]]
    },
    "pdfs": {
      "use": "accepted_files",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "=", "application/pdf"]]
    },
    "image_thumb": {
      "use": "images",
      "robot": "/image/resize",
      "width": 600,
      "height": 600,
      "resize_strategy": "fit",
      "format": "webp",
      "result": true
    },
    "document_thumb": {
      "use": "pdfs",
      "robot": "/document/thumbs",
      "format": "jpg",
      "page": 1,
      "width": 600,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_files", "image_thumb", "document_thumb"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "filestack-import/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Los dos filtros de enrutamiento usan tipos MIME para mantener las imágenes y los PDF en ramas de vista previa separadas. Los originales rechazados nunca entran al Step de exportación. Una Assembly no es una transacción: los archivos aceptados que ya se exportaron no se revierten si falla otro archivo. Ignorar errores suprime los fallos; no sustituye al enrutamiento ni a la validación.

Haz un seguimiento de los objetos de almacenamiento escritos por cada intento de reprocesamiento masivo. Antes de reintentar una Assembly fallida, reconcilia o elimina sus exportaciones parciales para que los reintentos no dejen objetos duplicados o huérfanos. No publiques intentos fallidos en tu aplicación, aunque algunos archivos se hayan exportado correctamente.

Configura tu CDN para leer desde la raíz del bucket; url_prefix solo cambia las URL devueltas. acl: "bucket-default" no envía ninguna ACL de objeto; configura el acceso mediante la política de tu bucket y el acceso de origen de tu CDN. Después de ASSEMBLY_COMPLETED, lee los originales aceptados desde results.accepted_files y las vistas previas desde results.image_thumb y results.document_thumb. La exportación agrega o actualiza entradas bajo los Steps nombrados en su parámetro use, a menos que ese Step establezca explícitamente result: false. Conserva solo las entradas con is_temp_url: false. Las URL temporales de Transloadit caducan después de 24 horas; consulta Guardar los archivos de resultados.

Reemplaza la selección de archivos

Para integraciones en el navegador, reemplaza el picker de Filestack con Uppy. Uppy puede seleccionar archivos locales, subidas mediante arrastrar y soltar, y conectar orígenes remotos. El Transloadit Plugin envía los archivos a una Assembly usando tu Template. Habilita waitForEncoding para recibir los resultados del procesamiento terminado en el navegador, o establece notify_url en tu solicitud de Assembly firmada y gestiona las Assembly Notifications en tu backend. Verifica las firmas de las notificaciones y exige la finalización exitosa antes de actualizar tu base de datos.

La respuesta del Picker⁠ de Filestack contiene handles de archivo, URL y metadatos de subida; onUploadDone informa de los archivos subidos y fallidos. Reescribe los manejadores que esperan esa forma de respuesta, y prueba la cancelación, los reintentos, los tipos/tamaños de archivo permitidos, la accesibilidad y cada flujo de autorización de origen remoto. Mantén las etiquetas de catálogo en tu backend y asócialas con tu ID de activo en lugar de asumir que los metadatos del picker sobreviven a la exportación.

Reemplaza la automatización y la seguridad de forma deliberada. Los webhooks⁠ de Filestack tienen cargas útiles específicas por evento y usan los encabezados FS-Timestamp y FS-Signature para la verificación. Los resultados de los trabajos de su flujo de trabajo no son una carga útil de Assembly Status. Implementa el receptor de Transloadit usando su propio contrato documentado y su propio esquema de firmas. Haz que las actualizaciones de la base de datos sean idempotentes, conserva el ID de la Assembly y reconcilia las exportaciones parciales antes de reintentar el procesamiento. Separa la finalización de la subida de un procesamiento y exportación exitosos antes de publicar un activo.

Las políticas de seguridad⁠ de Filestack usan políticas en Base64URL firmadas con HMAC-SHA256 y pueden restringir la caducidad, las llamadas, los handles, las rutas/contenedores de subida y el tamaño. La autenticación de subida y de entrega son configurables; haz un inventario de lo que tu aplicación realmente aplica. Recrea la autorización de subida usando la autenticación de Transloadit en tu backend, y configura la autorización de descarga con tu almacenamiento/CDN. Las políticas y firmas existentes de Filestack no autorizan al servicio de reemplazo. Nunca hagas públicas exportaciones privadas solo para reemplazar una URL de origen firmada. El ajuste de acceso de subida a S3⁠ de Filestack controla el acceso a los objetos almacenados; revisa la política del bucket de destino, el acceso de origen del CDN y cualquier esquema de descarga firmada por separado de la autenticación de la Assembly. Los ejemplos de exportación establecen acl: "bucket-default"; verifica la política de destino antes de la migración.

El Virus Detection⁠ de Filestack se ejecuta de forma asíncrona mediante flujos de trabajo después de la subida al almacenamiento. Si lo usas, diseña y prueba la validación de escaneo/cuarentena de reemplazo antes de publicar los originales o las vistas previas. Ni el filtrado por tipo MIME ni una subida exitosa demuestran que un archivo sea seguro.

Ten en cuenta las herramientas de agentes. El Filestack Claude Plugin⁠ expone herramientas para subidas, transformaciones, firma de políticas, ejecución de flujos de trabajo y verificación de webhooks. Haz un inventario de las URL y los flujos de trabajo realmente generados o invocados por esas herramientas. Reconstruye las operaciones necesarias con definiciones de Template revisadas y llamadas de SDK/API; esta guía no ofrece un reemplazo directo para el plugin ni para sus modelos de inteligencia. Conserva las revisiones de Template, los IDs de las Assemblies, las verificaciones de resultados y las decisiones de reintento para soporte e inspección. Calcula los costos de procesamiento y almacenamiento para un lote de muestra, limita la concurrencia y los reintentos del reprocesamiento masivo, y revisa los flujos de datos regionales, la retención y los requisitos de cumplimiento antes de autorizar la migración completa. Esta guía no establece el cumplimiento normativo ni una configuración de enrutamiento regional.

Importa las URL existentes de Filestack

Las URL de CDN⁠ de Filestack identifican los archivos por handle. Selecciona la URL original autorizada, sin tareas de transformación, y proporciona una política/firma de lectura válida si la seguridad del origen lo requiere. Haz que su caducidad sea lo bastante larga para la descarga en cola, y mantén las URL de origen firmadas fuera de los registros y manifiestos públicos. Si se resuelve en una URL HTTPS descargable, mígrala con 🤖/http/import:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.filestack_url}"
    },
    "preview": {
      "use": "imported",
      "robot": "/file/preview",
      "result": true
    },
    "exported": {
      "use": ["imported", "preview"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "filestack-backfill/${unique_prefix}/${file.url_name}",
      "acl": "bucket-default"
    }
  }
}

Selecciona valores filestack_url autorizados del inventario de activos de tu backend. /file/preview está en beta y recurre a un ícono genérico de tipo de archivo cuando no puede generar una miniatura del contenido. Ejecuta trabajos de reprocesamiento masivo acotados; /http/import también acepta un array de URL. Conserva los handles y URL de origen hasta verificar el acceso y la calidad de la exportación completada. Los objetos privados de S3 necesitan una descarga autorizada o tu CDN configurado. El Template de importación devuelve los archivos exportados bajo results.imported y results.preview.

Reemplaza las URL de entrega después de la verificación. Conserva una correspondencia entre cada handle antiguo más su receta de transformación y su nueva URL exportada. Verifica los checksums originales, la apariencia de las derivaciones, los tipos MIME y el acceso autorizado/público antes de actualizar los registros de la base de datos, el marcado renderizado, el CSS, el contenido del CMS y las respuestas de la API. Regenera las derivaciones necesarias en lugar de añadir tareas de Filestack al nuevo nombre de host del CDN. Conserva los registros antiguos y una ruta de lectura reversible por si necesitas revertir, mientras las nuevas subidas usan la nueva ruta.

Puedes redirigir URL servidas desde un dominio que controlas. Si usas el CNAME personalizado⁠ de Filestack, reemplaza su origen solo después de que tu capa de entrega pueda resolver las rutas antiguas de handle/tarea y aplicar las reglas de acceso previstas. No puedes instalar tus redirecciones en el dominio compartido cdn.filestackcontent.com de Filestack: reemplaza esos enlaces en el contenido que controlas y planifica el acceso continuo al origen para las referencias que no puedas actualizar. Prueba el comportamiento de la caché y los controles de acceso antes de hacer permanentes las redirecciones.

Lista de verificación

Estimación de planificación. Para un picker, un inventario de activos accesible, algunas recetas de vista previa y un bucket que controlas, presupuesta varios días de ingeniería para un piloto probado. Un reprocesamiento masivo grande, la compatibilidad con dominios personalizados, la entrega privada, los visores de documentos y las exportaciones de catálogo/versiones propiedad de la aplicación pueden tomar semanas o más. Estas son estimaciones de planificación, no referencias de migración medidas; cronometra un lote representativo e incluye los límites de transferencia, el costo de procesamiento, la validación y la reversión.

1. Haz un inventario de los handles, rutas de almacenamiento, etiquetas/descripciones, versiones, callbacks del picker, reglas de seguridad, recetas de transformación, tareas de flujo de trabajo y uso de herramientas de agentes. Resuelve cualquier función excluida antes de la migración definitiva.
2. Elige las claves de objeto de destino, el almacenamiento de catálogo, la autorización de descarga, el CDN y la estrategia para las URL antiguas. Configura las credenciales de terceros con el acceso necesario.
3. Crea y verifica los Templates con imágenes, PDF, archivos no compatibles y fallos representativos. Incluye una validación de escaneo/cuarentena si es necesario.
4. Reemplaza el picker y el receptor de webhooks en un piloto. Verifica el manejo de la finalización, las comprobaciones de firma, los reintentos, la idempotencia y el acceso de descarga privado.
5. Ejecuta un reprocesamiento masivo acotado; registra las exportaciones completadas y reconcilia los intentos parciales. Compara los checksums originales y la calidad de las derivaciones antes de cambiar la ruta de lectura de cualquier activo.
6. Cambia las subidas nuevas, reconcilia la diferencia final del origen y luego migra las lecturas por cohortes. Supervisa los errores, los costos y el tráfico de las URL antiguas; conserva una ruta de reversión y acceso al origen hasta la aprobación final.