Sua primeira integração da Transloadit com Node.js

A integração útil mais curta com a Transloadit é um script no lado do servidor que faz o upload de uma imagem e gera uma versão derivada. Ela comprova que as credenciais, a transferência de arquivos, o processamento e o tratamento de resultados funcionam antes que um navegador, um destino de armazenamento, um banco de dados ou um webhook acrescentem mais partes móveis.

O que mais importa

• Trate o arquivo retornado como temporário até que um Step de exportação o armazene permanentemente.

mkdir transloadit-quickstart
cd transloadit-quickstart
npm init -y
npm pkg set type=module
npm install @transloadit/node

import { Transloadit } from '@transloadit/node'

async function main(): Promise<void> {
  const authKey = process.env.TRANSLOADIT_KEY
  const authSecret = process.env.TRANSLOADIT_SECRET
  const inputPath = process.argv[2]

  if (authKey == null || authSecret == null || inputPath == null) {
    throw new Error(
      'Set TRANSLOADIT_KEY and TRANSLOADIT_SECRET, then pass an image path.',
    )
  }

  const transloadit = new Transloadit({ authKey, authSecret })
  const assembly = await transloadit.createAssembly({
    files: { image: inputPath },
    params: {
      steps: {
        ':original': {
          robot: '/upload/handle',
        },
        resized: {
          use: ':original',
          robot: '/image/resize',
          result: true,
          width: 400,
          height: 400,
          resize_strategy: 'fit',
        },
      },
    },
    waitForCompletion: true,
  })

  const result = assembly.results?.resized?.[0]
  if (result == null) {
    throw new Error(`Assembly ${assembly.assembly_id} produced no resized result.`)
  }

  console.log(`Result: ${result.ssl_url}`)
  console.log(`Assembly: ${assembly.assembly_id}`)
}

main().catch((error: unknown) => {
  if (!(error instanceof Error)) {
    throw new Error(`Was thrown a non-error: ${error}`)
  }

  console.error(error.message)
  process.exit(1)
})

env \
  TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY" \
  TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET" \
  node quickstart.ts ./your-image.jpg

Detalhes técnicos que vale a pena conhecer

• Uma Assembly corresponde a uma única execução das Assembly Instructions. Cada Step de processamento invoca um único Robot e declara sua entrada anterior com use; o Step de upload reservado :original é a origem e não recebe use.
• O SDK para Node gera a autenticação das requisições a partir da Auth Key e do Auth Secret. O segredo deve ficar apenas em um processo de servidor confiável, nunca em JavaScript do navegador ou em um aplicativo móvel.
• Definir waitForCompletion como true faz o SDK consultar o status periodicamente até que a Assembly atinja um estado terminal, o que é conveniente para uma primeira execução pequena, mas inadequado para manipuladores de requisição demorados.
• A flag result marca os arquivos de um Step para inclusão no objeto results de nível superior da Assembly. Isso não torna os arquivos permanentes.
• Por padrão, os arquivos temporários da Assembly ficam disponíveis por cerca de 24 horas e para um número limitado de recuperações. Não sirva as URLs deles diretamente aos usuários finais; adicione um Robot de exportação para arquivos destinados aos usuários.
• O Assembly ID é uma referência privada útil para depuração, mas qualquer pessoa que tenha esse ID ou a URL de status pode ler o Assembly Status sem nenhuma autenticação adicional. Mantenha ambos fora de logs públicos e de respostas ao cliente; use o identificador de job da sua própria aplicação nessas superfícies.

Uma abordagem prática

Quando a Transloadit é útil

Use o Node SDK para criar uma Assembly contendo /upload/handle e /image/resize. O SDK assina a requisição com credenciais do lado do servidor, faz o upload do arquivo local, aguarda a conclusão e retorna a URL do resultado e o Assembly ID.

Limite da arquitetura

Este guia rápido roda em um servidor confiável e aguarda até que uma imagem pequena termine de ser processada. Uma integração no navegador precisa receber de um backend parâmetros assinados e de curta duração, enquanto, em produção, o trabalho em segundo plano deve preferencialmente usar um webhook verificado em vez de manter uma requisição HTTP aberta.