Migrar do Filestack para a Transloadit

O Filestack oferece seleção de arquivos, uploads, armazenamento e transformações via CDN⁠ e Workflows assíncronos⁠. Com a Transloadit, o Uppy cuida da seleção no navegador e os Robots cuidam do processamento de arquivos. Defina um fluxo de trabalho suportado em um Template e, em seguida, use um SDK, o Uppy ou a REST API para criar Assemblies. Verifique individualmente as tarefas que a sua aplicação usa; o mapeamento abaixo não promete paridade total de recursos.

Este guia aborda o processamento e a exportação de arquivos para um armazenamento que você controla. Ele não implementa uma migração hospedada para o DAM da Transloadit. Importar para uma Media Library hospedada, preservar suas pastas e metadados, a entrega via tlcdn.com, execuções de teste e manifestos de migração, e papéis, widgets e integrações de CMS/editor da Media Library exigem um plano de migração separado. O inventário descrito abaixo é um registro de migração mantido pela sua própria aplicação, não uma ferramenta de migração de DAM hospedada.

Mapa de migração

Os aliases de armazenamento do Filestack expõem um armazenamento externo já existente ao seu serviço de processamento sem um upload através do Filestack. Se você já possui o bucket de origem, decida se os originais podem permanecer lá enquanto você processa e exporta as novas derivações. Para armazenamento gerenciado pelo Filestack, baixe os originais autorizados pela CDN⁠ antes de encerrar a conta. Este guia não fornece um script de exportação em massa da conta ou de descoberta de assets.

Preserve o catálogo separadamente. Antes de copiar os bytes, registre o ID do seu asset, o handle do Filestack, a URL de download original, o local/container/caminho de armazenamento, o nome do arquivo, o tipo MIME, o tamanho, o checksum e as derivações necessárias. O endpoint de metadados⁠ do Filestack pode retornar fatos sobre o arquivo, informações de armazenamento e hashes; ele gera essas informações sob demanda. Mantenha o inventário de origem e o mapeamento concluído de Assembly/exportação no seu próprio banco de dados.

As tags de upload do Picker⁠ do Filestack são retornadas em respostas de upload e webhooks. O DAM⁠ dele também permite que os usuários editem tags e descrições de assets. Preserve esses registros separadamente dos metadados do arquivo; os Templates abaixo copiam e processam bytes, não tags ou descrições de catálogo. Use os caminhos de armazenamento registrados para decidir como as chaves de objeto de destino preservam as pastas; estes exemplos geram novos caminhos. Inventarie quaisquer coleções e relações de revisão que a sua aplicação usa, incluindo sua ordem e permissões. A operação de sobrescrita⁠ do Filestack substitui o arquivo por trás de um handle, então um download não é uma exportação do histórico de versões. Este guia não exporta a associação a coleções nem as revisões históricas; obtenha-as da sua aplicação ou do arquivo existente antes de migrar, se forem necessárias.

Crie um Template para cada fluxo de trabalho

Traduza as receitas de transformação. O Processing Engine⁠ do Filestack aceita tarefas em URLs de CDN, enquanto os Workflows dele definem tarefas e lógica condicional. Inventarie toda a cadeia de tarefas, os parâmetros, as predefinições nomeadas da aplicação, os IDs de fluxo de trabalho e as condições usadas por cada view da aplicação. Reconstrua as receitas necessárias como Templates, gere as derivações e compare imagens e documentos representativos quanto a corte, proporção, orientação, seleção de página, qualidade e formato. Um Robot de miniaturas não substitui o Filestack Document Viewer⁠ interativo; escolha um visualizador separado se a sua aplicação precisar de um. Os exemplos abaixo cobrem pré-visualizações de imagem/PDF e uma pré-visualização genérica de arquivo; eles não reproduzem todas as tarefas de transformação ou inteligência do Filestack.

Este Template verifica o tipo MIME detectado, cria uma miniatura de imagem ou uma miniatura da primeira página de um PDF, e armazena os originais e as pré-visualizações aceitos. Outros tipos MIME interrompem a Assembly com um erro. Isso é filtragem por tipo, não verificação de malware; adicione /file/virusscan se o seu fluxo de trabalho exigir isso:

{
  "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"
    }
  }
}

Os dois filtros de roteamento usam tipos MIME para manter imagens e PDFs em ramificações de pré-visualização separadas. Originais recusados nunca entram no Step de exportação. Uma Assembly não é uma transação: arquivos aceitos já exportados não são revertidos se outro arquivo falhar. Ignorar erros suprime falhas; não é um substituto para roteamento ou validação.

Acompanhe os objetos de armazenamento gravados por cada tentativa de preenchimento retroativo. Antes de repetir uma Assembly com falha, reconcilie ou exclua suas exportações parciais para que as novas tentativas não deixem objetos duplicados ou órfãos. Não publique tentativas com falha na sua aplicação, mesmo que alguns arquivos tenham sido exportados com sucesso.

Configure a sua CDN para ler a raiz do bucket; url_prefix apenas altera as URLs retornadas. acl: "bucket-default" não envia nenhuma ACL de objeto; configure o acesso por meio da política do seu bucket e do acesso de origem da CDN. Após ASSEMBLY_COMPLETED, leia os originais aceitos em results.accepted_files e as pré-visualizações em results.image_thumb e results.document_thumb. A exportação adiciona ou atualiza entradas sob os Steps nomeados no seu parâmetro use, a menos que esse Step defina explicitamente result: false. Persista apenas as entradas com is_temp_url: false. As URLs temporárias da Transloadit expiram após 24 horas; veja salvando resultados de conversão.

Substitua a seleção de arquivos

Para integrações no navegador, substitua o picker do Filestack pelo Uppy. O Uppy pode selecionar arquivos locais, uploads via arrastar e soltar, e conectar fontes remotas. O Transloadit Plugin envia arquivos para uma Assembly usando o seu Template. Ative waitForEncoding para receber os resultados do processamento concluído no navegador, ou defina notify_url na sua requisição assinada de Assembly e trate Assembly Notifications no seu backend. Verifique as assinaturas das notificações e exija a conclusão bem-sucedida antes de atualizar o seu banco de dados.

A resposta do Picker⁠ do Filestack contém handles de arquivo, URLs e metadados de upload; onUploadDone relata arquivos enviados e com falha. Reescreva os handlers que esperam esse formato de resposta e teste cancelamento, novas tentativas, tipos/tamanhos de arquivo permitidos, acessibilidade e cada fluxo de autorização de fonte remota. Mantenha as tags de catálogo no seu backend e associe-as ao ID do seu asset, em vez de presumir que os metadados do picker sobrevivem à exportação.

Substitua a automação e a segurança de forma deliberada. Os webhooks⁠ do Filestack têm payloads específicos para cada evento e usam os cabeçalhos FS-Timestamp e FS-Signature para verificação. Os resultados de jobs de fluxo de trabalho dele não são um payload de Assembly Status. Implemente o receptor da Transloadit usando o contrato e o esquema de assinatura documentados próprios dele. Torne as atualizações do banco de dados idempotentes, retenha o ID da Assembly e reconcilie exportações parciais antes de repetir o processamento. Separe a conclusão do upload do processamento e da exportação bem-sucedidos antes de publicar um asset.

As políticas de segurança⁠ do Filestack usam políticas em Base64URL assinadas com HMAC-SHA256 e podem restringir expiração, chamadas, handles, caminhos/containers de upload e tamanho. A autenticação de upload e de entrega é configurável; inventarie o que a sua aplicação realmente aplica. Recrie a autorização de upload usando a autenticação da Transloadit no seu backend e configure a autorização de download com o seu armazenamento/CDN. As políticas e assinaturas existentes do Filestack não autorizam o serviço substituto. Nunca torne públicas exportações privadas apenas para substituir uma URL de origem assinada. A configuração de acesso a upload do S3⁠ do Filestack controla o acesso a objetos armazenados; revise a política do bucket de destino, o acesso de origem da CDN e qualquer esquema de download assinado separadamente da autenticação da Assembly. Os exemplos de exportação definem acl: "bucket-default"; verifique a política de destino antes da migração.

A Detecção de vírus⁠ do Filestack é executada de forma assíncrona através dos Workflows após o upload para o armazenamento. Se você a usa, projete e teste o portão de verificação/quarentena substituto antes de publicar originais ou pré-visualizações. Nem a filtragem por MIME nem um upload bem-sucedido comprovam que um arquivo é seguro.

Considere as ferramentas de agente. O Filestack Claude Plugin⁠ expõe ferramentas para uploads, transformações, assinatura de políticas, execução de fluxos de trabalho e verificação de webhook. Inventarie as URLs e os fluxos de trabalho reais gerados ou invocados por essas ferramentas. Reconstrua as operações necessárias com definições de Template revisadas e chamadas de SDK/API; este guia não oferece uma substituição pronta para o plugin ou seus modelos de inteligência. Mantenha as revisões de Template, os IDs de Assembly, as verificações de saída e as decisões de nova tentativa para suporte e inspeção. Estime os custos de processamento e armazenamento para um lote de amostra, limite a concorrência e as novas tentativas do preenchimento retroativo, e revise os fluxos regionais de dados, a retenção e os requisitos de conformidade antes de autorizar a migração completa. Este guia não estabelece conformidade regulatória nem uma configuração de roteamento regional.

Importe URLs existentes do Filestack

As URLs de CDN⁠ do Filestack identificam arquivos por handle. Selecione a URL original autorizada, sem tarefas de transformação, e forneça uma política/assinatura de leitura válida se a segurança da origem exigir uma. Torne a expiração longa o suficiente para o download em fila e mantenha URLs de origem assinadas fora de logs e manifestos públicos. Se ela resolver para uma URL HTTPS baixável, migre-a com o 🤖/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"
    }
  }
}

Selecione valores filestack_url autorizados a partir do inventário de assets do seu backend. /file/preview está em beta e recorre a um ícone genérico de tipo de arquivo quando não consegue gerar uma miniatura de conteúdo. Execute jobs de preenchimento retroativo limitados; /http/import também aceita um array de URLs. Mantenha os handles e URLs de origem até que o acesso e a qualidade da exportação concluída sejam verificados. Objetos S3 privados precisam de um download autorizado ou da sua CDN configurada. O Template de importação retorna arquivos exportados em results.imported e results.preview.

Substitua as URLs de entrega após a verificação. Mantenha um mapeamento de cada handle antigo mais a receita de transformação para a sua nova URL exportada. Verifique checksums originais, aparência das derivações, tipos MIME e acesso autorizado/público antes de atualizar registros do banco de dados, markup renderizado, CSS, conteúdo de CMS e respostas de API. Regenere as derivações necessárias em vez de anexar tarefas do Filestack ao novo hostname da CDN. Mantenha os registros antigos e um mecanismo de troca do caminho de leitura para rollback enquanto os novos uploads usam o novo caminho.

Você pode redirecionar URLs servidas a partir de um domínio que você controla. Se você usa o CNAME personalizado⁠ do Filestack, substitua a origem dele apenas depois que a sua camada de entrega puder resolver caminhos antigos de handle/tarefa e aplicar as regras de acesso pretendidas. Você não pode instalar seus redirecionamentos no domínio compartilhado cdn.filestackcontent.com do Filestack: substitua esses links no conteúdo que você controla e planeje o acesso contínuo à origem para referências que você não pode atualizar. Teste o comportamento de cache e os controles de acesso antes de tornar os redirecionamentos permanentes.

Lista de verificação

Estimativa de planejamento. Para um picker, um inventário de assets acessível, algumas receitas de pré-visualização e um bucket que você controla, reserve vários dias de engenharia para um piloto testado. Um grande preenchimento retroativo, compatibilidade com domínio personalizado, entrega privada, visualizadores de documentos e exportações de catálogo/versão mantidas pela aplicação podem levar semanas ou mais. Essas são estimativas de planejamento, não benchmarks de migração medidos; cronometre um lote representativo e inclua limites de transferência, custo de processamento, validação e rollback.

1. Inventarie handles, caminhos de armazenamento, tags/descrições, versões, callbacks do picker, regras de segurança, receitas de transformação, tarefas de fluxo de trabalho e uso de ferramentas de agente. Resolva qualquer recurso excluído antes do corte de migração.
2. Escolha as chaves de objeto de destino, o armazenamento de catálogo, a autorização de download, a CDN e a estratégia para URLs antigas. Configure Credenciais de terceiros com o acesso necessário.
3. Crie e verifique Templates com imagens, PDFs, arquivos não suportados e falhas representativos. Inclua um portão de verificação/quarentena, se necessário.
4. Substitua o picker e o receptor de webhook em um piloto. Verifique o tratamento de conclusão, as verificações de assinatura, as novas tentativas, a idempotência e o acesso privado a downloads.
5. Execute um preenchimento retroativo limitado; registre as exportações concluídas e reconcilie as tentativas parciais. Compare checksums originais e a qualidade das derivações antes de trocar o caminho de leitura de qualquer asset.
6. Troque os novos uploads, reconcilie o delta final da origem e, em seguida, migre as leituras em coortes. Monitore erros, custos e tráfego de URLs antigas; mantenha um caminho de rollback e acesso à origem até a aprovação final.