Migrar do Uploadcare para a Transloadit

O Uploadcare oferece APIs de upload, gerenciamento e URL⁠, incluindo entrega via CDN e grupos de arquivos⁠. A Transloadit separa essas responsabilidades em Robots de upload/importação, Robots de processamento, Robots de exportação e entrega opcional via CDN. Faça um inventário das operações que você usa e mapeie as tarefas de processamento suportadas para Steps em um Template da Transloadit; isso não é uma substituição um-para-um de todos os recursos do Uploadcare.

Este guia move uploads e processamento para Templates e exporta arquivos para o seu próprio armazenamento. Ele não implementa importações hospedadas do DAM da Transloadit, migração gerenciada de pastas/metadados, troca de entrega tlcdn.com, simulações/manifestos de migração, papéis da Media Library, seletores de assets ou integrações com CMS/editores. Esses casos exigem um plano separado de migração do DAM.

Mapa de migração

Use dependências de Step para direcionar arquivos entre tarefas de processamento, não para substituir registros persistentes de grupos de arquivos. Assine URLs do Smart CDN no seu backend e use um Template compatível separado para entrega sob demanda.

Decisões de transformação. Faça um inventário das cadeias completas de operações de URL, presets da aplicação, coordenadas de corte, orientação, dimensões, qualidade e formato. O format/auto⁠ do Uploadcare seleciona formatos com base nos recursos do navegador; o avatar WebP fixo abaixo não reproduz essa negociação. Compare as saídas em imagens representativas, incluindo transparência e animação. Conversões de vídeo precisam de seus próprios Templates; nenhum dos exemplos abaixo migra streaming de vídeo, conversão de documentos, todas as operações de URL ou plugins personalizados de uploader.

Moderação é um fluxo de trabalho separado. A moderação de conteúdo inseguro⁠ do Uploadcare pode escanear imagens no upload ou por meio de um complemento REST assíncrono, com resultados em appdata. Preserve o resultado e a política de moderação, incluindo limites e decisões de exclusão/revisão, no seu inventário de migração. Estes exemplos otimizam ou pré-visualizam arquivos; eles não recriam essa barreira de moderação. Escolha e valide uma substituição antes de publicar UGC, e mantenha a barreira existente até que ela esteja pronta. Filtragem de MIME, verificação de malware e detecção de conteúdo impróprio resolvem problemas diferentes.

Substitua o widget de upload

Para uploads pelo navegador, use o Uppy com o Transloadit Plugin. O Uppy oferece um seletor de arquivos, interface de arrastar e soltar, uploads retomáveis, fontes remotas e integração direta com a Transloadit.

Um fluxo típico do Uploadcare, em que os usuários fazem upload de uma imagem e recebem URLs de CDN transformadas, se torna:

1. O navegador faz upload por meio do Uppy e referencia um Template salvo da Transloadit.
2. O Template cria todas as variantes de que sua aplicação precisa.
3. A Transloadit notifica seu backend com as URLs do resultado.
4. Seu backend armazena essas URLs no seu banco de dados.

Configure uma notify_url na requisição assinada da Assembly e verifique as assinaturas das notificações recebidas. Para conclusão no lado do navegador, ative o waitForEncoding do Uppy; o padrão só aguarda o upload.

Reescreva callbacks que esperam UUIDs do Uploadcare, IDs de grupo ou URLs de operação de CDN. Mantenha seu próprio ID de asset e associe-o à Assembly concluída e aos arquivos exportados. Teste fontes locais e remotas, retomada, cancelamento, validação e falhas; substituir a interface de upload não substitui um navegador de assets ou integração de CMS existente.

Os webhooks⁠ do Uploadcare cobrem eventos de upload, informação de arquivo, armazenamento e exclusão. Seu segredo de assinatura opcional produz um cabeçalho X-Uc-Signature, e entregas malsucedidas são repetidas. Mapeie a conclusão do processamento para Assembly Notifications, trate eventos de catálogo e exclusão na sua aplicação e use a verificação de notificação da própria Transloadit. Torne as atualizações idempotentes por Assembly ID e exija exportação bem-sucedida antes de publicar. Teste o comportamento de nova tentativa e reconciliação em vez de reaproveitar o payload de evento ou a programação de repetição antigos.

Decisões de segurança. Os uploads assinados⁠ do Uploadcare autorizam a ingestão; a entrega assinada⁠, separadamente, restringe o acesso por meio de um subdomínio de CDN seguro ou domínio personalizado configurado. Faça um inventário dos caminhos públicos e privados, da expiração de tokens e das variantes permitidas. Use requisições da Transloadit assinadas no backend para os Templates e campos permitidos e, em seguida, aplique a autorização de download por meio do seu bucket/CDN. Uma requisição assinada de Assembly não concede nem restringe o acesso a um objeto S3 exportado. Não torne arquivos privados públicos para simplificar a migração. Se você usa a proteção contra malware do Uploadcare⁠, adicione e teste um Step de verificação explícito e uma barreira de quarentena/publicação; os Templates apresentados não verificam arquivos. A implementação completa de ACL, a qualificação de conformidade e o roteamento regional estão fora dos exemplos deste guia.

Template de exemplo

Este Template recebe o upload de uma imagem, cria um avatar quadrado em WebP, otimiza tanto o original quanto o avatar, e armazena os arquivos otimizados no S3. A otimização não tem parâmetro de formato e, com progressive desativado como aqui, retorna o original se o arquivo otimizado for maior. Ativar progressive permite manter um resultado de otimização mesmo que ele seja maior:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "avatar": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 512,
      "height": 512,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "optimized_original": {
      "use": ":original",
      "robot": "/image/optimize",
      "result": true
    },
    "optimized_avatar": {
      "use": "avatar",
      "robot": "/image/optimize",
      "result": true
    },
    "exported": {
      "use": ["optimized_original", "optimized_avatar"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "uploads/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Configure credenciais de terceiros para o S3 e configure sua CDN para servir a raiz do bucket com acesso de leitura. url_prefix não cria uma CDN nem concede acesso. O 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. Depois de ASSEMBLY_COMPLETED, leia o original em results.optimized_original e o avatar em results.optimized_avatar. Persista apenas as entradas com is_temp_url: false: a exportação atualiza as URLs do Step que a produz. URLs temporárias da Transloadit expiram após 24 horas; veja salvando resultados de conversão.

Importe arquivos existentes do Uploadcare

Faça um inventário dos originais e dos dados de catálogo. Enumere os UUIDs referenciados pela sua aplicação e reconcilie-os com o inventário de arquivos da REST API⁠ do projeto, seguindo a paginação. As informações do arquivo⁠ incluem original_file_url, original_filename, tamanho do arquivo, status de armazenamento e dados de processamento. Selecione o download original autorizado para cada arquivo; se original_file_url estiver ausente ou o arquivo tiver sido removido, resolva essa lacuna antes de migrar o registro. Obtenha novas URLs de origem assinadas no seu backend quando necessário.

Preserve metadados arbitrários⁠, tags⁠ e appdata relevantes no seu banco de dados ou em registros auxiliares; importar os bytes não os copia. Os grupos de arquivos⁠ são coleções imutáveis com membros indexados, e um membro pode incluir uma receita de transformação. Registre o ID do grupo, os UUIDs dos membros em ordem e as receitas separadamente. Uma Assembly processa arquivos, mas não recria essa coleção persistente. Preserve caminhos de pasta, outros relacionamentos de coleção e o histórico de revisões mantido pela sua aplicação, atribuindo chaves de armazenamento distintas às revisões; estes Templates não descobrem nem exportam revisões históricas ou relacionamentos exclusivos da aplicação.

Se você já tem URLs de download autorizadas do Uploadcare no seu inventário, importe-as com o 🤖/http/import:

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

O Step de pré-visualização usa o 🤖/file/preview EN (English) (beta); ele pode retornar um ícone genérico de tipo de arquivo quando uma miniatura de conteúdo não está disponível. Selecione valores uploadcare_url autorizados no seu backend. Importar uma URL de CDN transformada copia essa renderização, não necessariamente o original. Você pode preencher retroativamente apenas os arquivos referenciados ou passar um array de URLs autorizadas para /http/import em um lote limitado. Mantenha um mapeamento de ID antigo para nova localização e verifique o acesso de entrega e a qualidade da saída antes de trocar as leituras. Este Template de importação retorna os arquivos exportados em results.imported e results.preview. Objetos privados do S3 precisam de um download autorizado ou da sua CDN configurada.

Lista de verificação

Troca de entrega. Registre um mapeamento de cada UUID e cadeia de operações usada para o destino verificado. Substitua URLs em registros da aplicação, páginas renderizadas, srcset, CSS, e-mail e conteúdo de CMS; anexar a sintaxe de operações do Uploadcare a um novo nome de host de armazenamento não a aplica. Use redirecionamentos apenas em um domínio ou rota de aplicação que você controla, com um resolvedor para os caminhos antigos e as regras de acesso pretendidas. Para URLs de CDN de propriedade do provedor, atualize as referências que você controla e mantenha o acesso à origem durante o período de sobreposição. Teste autorização, cache e páginas reais antes de tornar os redirecionamentos permanentes ou excluir os arquivos de origem.

Estimativa de planejamento. Para um uploader, algumas variantes de imagem, um inventário acessível e um bucket/CDN existente, reserve vários dias de engenharia para um piloto testado, seguidos do tempo medido de preenchimento retroativo. Entrega privada, grupos, moderação, mudanças de CMS e exportações de revisão/catálogo podem exigir semanas ou mais. Esta é uma estimativa de planejamento de engenharia, não um benchmark de migração medido. Meça a taxa de transferência e o custo de importação, processamento e exportação em um lote representativo, incluindo downloads de origem, entrega no destino e o período em que ambos os serviços rodam simultaneamente.

1. Faça um inventário de originais, metadados, tags, ordem/receitas de grupo, revisões, regras de acesso, operações, callbacks do uploader e resultados de moderação. Resolva recursos excluídos antes da troca.
2. Versione as Instructions do Template no seu repositório e teste as variantes e barreiras necessárias. Mantenha as revisões do Template, Assembly IDs, falhas e mapeamentos de destino para suporte.
3. Configure credenciais, acesso a armazenamento/CDN, assinatura e o receptor de notificações. Verifique a entrega durável e o tratamento de duplicatas/falhas em um piloto.
4. Defina tamanhos de lote limitados, concorrência, limites de nova tentativa e um orçamento de migração. Confirme as regiões de processamento e armazenamento, retenção e requisitos de conformidade antes de mover os dados.
5. Troque novos uploads por trás de uma feature flag, preencha retroativamente em lotes limitados e reconcilie exportações parciais antes de novas tentativas. Compare originais, derivados, contagens de catálogo e acesso privado.
6. Atualize as leituras e referências de entrega em coortes, mantendo o mapeamento de origem para rollback. Reconcilie o delta final da origem e mantenha a entrega antiga disponível até que a janela de rollback e os tempos de vida do cache tenham passado.