Tu primera integración de Transloadit con Node.js

La integración útil más corta con Transloadit es un script del lado del servidor que sube una imagen y produce un derivado. Demuestra que las credenciales, la transferencia de archivos, el procesamiento y el manejo de resultados funcionan antes de agregar un navegador, un destino de almacenamiento, una base de datos o un webhook, lo que añade más piezas móviles.

Lo más importante

• Trata el archivo devuelto como temporal hasta que un Step de exportación lo almacene de forma permanente.

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

Detalles técnicos que conviene conocer

• Una Assembly es una ejecución de las Assembly Instructions. Cada Step de procesamiento invoca a un Robot y declara su entrada previa con use; el Step de subida reservado :original es la fuente y no toma use.
• El SDK de Node genera la autenticación de la solicitud a partir de la Auth Key y el Auth Secret. El secreto debe residir únicamente en un proceso de servidor confiable, nunca en JavaScript de navegador ni en una aplicación móvil.
• Establecer waitForCompletion en true hace que el SDK sondee hasta que la Assembly alcance un estado terminal, lo cual es conveniente para una primera ejecución pequeña pero inadecuado para manejadores de solicitudes de larga duración.
• La bandera result marca los archivos de un Step para su inclusión en el objeto results de nivel superior de la Assembly. No hace que los archivos sean permanentes.
• Los archivos temporales de la Assembly están disponibles durante unas 24 horas y un número limitado de recuperaciones de forma predeterminada. No sirvas sus URL directamente a los usuarios finales; agrega un Robot de exportación para los archivos orientados al usuario.
• El ID de la Assembly es una referencia privada útil para la depuración, pero quien tenga ese ID o la URL de estado puede leer Assembly Status sin más autenticación. Mantén ambos fuera de los registros públicos y de las respuestas al cliente; usa el identificador de trabajo propio de tu aplicación para esos contextos.

Un enfoque práctico

Cuándo resulta útil Transloadit

Usa el SDK de Node para crear una Assembly que contenga /upload/handle e /image/resize. El SDK firma la solicitud con credenciales del lado del servidor, sube el archivo local, espera a que finalice y devuelve la URL del resultado y el ID de la Assembly.

Límite de la arquitectura

Esta guía rápida se ejecuta en un servidor confiable y espera a que termine una imagen pequeña. Una integración en el navegador debe recibir parámetros firmados y de corta duración desde un back end, mientras que el trabajo en segundo plano en producción debería usar un webhook verificado en lugar de mantener abierta una solicitud HTTP.