Votre première intégration de Transloadit avec Node.js

L’intégration Transloadit utile la plus courte est un script côté serveur qui téléverse une seule image et produit une seule version dérivée. Elle démontre que les informations d’identification, le transfert de fichiers, le traitement et la gestion des résultats fonctionnent avant qu’un navigateur, une destination de stockage, une base de données ou un webhook n’ajoute de la complexité.

L’essentiel

• Considérez le fichier renvoyé comme temporaire tant qu’un Step d’export ne l’a pas stocké de façon 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

Détails techniques à connaître

• Une Assembly correspond à une exécution des Assembly Instructions. Chaque Step de traitement appelle un Robot et déclare son entrée en amont avec use ; le Step :original, réservé au téléversement, constitue la source et ne prend aucun use.
• Le SDK Node génère l’authentification des requêtes à partir de l’Auth Key et de l’Auth Secret. Le secret doit se trouver uniquement dans un processus serveur de confiance, jamais dans le JavaScript du navigateur ni dans une application mobile.
• Définir waitForCompletion sur true conduit le SDK à interroger périodiquement le statut jusqu’à ce que l’Assembly atteigne un état final. C’est pratique pour une première exécution de petite taille, mais inadapté aux gestionnaires de requêtes de longue durée.
• L’indicateur result marque les fichiers d’un Step pour qu’ils soient inclus dans l’objet results au niveau racine de l’Assembly. Il ne rend pas les fichiers permanents.
• Par défaut, les fichiers temporaires des Assemblies sont disponibles pendant environ 24 heures et pour un nombre limité de récupérations. Ne servez pas leurs URL directement aux utilisateurs finaux ; ajoutez un Robot d’exportation pour les fichiers destinés aux utilisateurs.
• L’identifiant d’Assembly est une référence de débogage utile et privée, mais toute personne qui le détient, ou qui détient l’URL de statut, peut lire l’Assembly Status sans authentification supplémentaire. Gardez les deux hors des journaux publics et des réponses client ; utilisez votre propre identifiant de tâche applicative pour ces usages.

Une approche pratique

Quand Transloadit est utile

Utilisez le SDK Node pour créer une Assembly contenant /upload/handle et /image/resize. Le SDK signe la requête avec des informations d’identification côté serveur, téléverse le fichier local, attend la fin du traitement et renvoie l’URL du résultat ainsi que l’identifiant de l’Assembly.

Périmètre architectural

Ce guide de démarrage rapide s’exécute sur un serveur de confiance et attend la fin du traitement d’une seule petite image. Une intégration dans le navigateur doit recevoir d’un backend des paramètres signés à courte durée de validité, tandis que les traitements en arrière-plan en production devraient utiliser un webhook vérifié au lieu de maintenir une requête HTTP ouverte.