Ihre erste Transloadit-Integration mit Node.js

Die kürzeste sinnvolle Transloadit-Integration ist ein serverseitiges Skript, das ein Bild hochlädt und ein Derivat erzeugt. Es beweist, dass Zugangsdaten, Dateiübertragung, Verarbeitung und Ergebnisbehandlung funktionieren, bevor ein Browser, ein Speicherziel, eine Datenbank oder ein Webhook weitere bewegliche Teile hinzufügen.

Worauf es besonders ankommt

• Behandeln Sie die zurückgegebene Datei als temporär, bis ein Export-Step sie dauerhaft speichert.

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

Wissenswerte technische Details

• Eine Assembly ist eine Ausführung von Assembly Instructions. Jeder Verarbeitungs-Step ruft einen Robot auf und deklariert seine vorgelagerte Eingabe über use; der reservierte :original-Upload-Step ist die Quelle und benötigt kein use.
• Das Node-SDK generiert die Anfrage-Authentifizierung aus Auth Key und Auth Secret. Das Secret gehört ausschließlich in einen vertrauenswürdigen Serverprozess, niemals in Browser-JavaScript oder eine mobile Anwendung.
• Wird waitForCompletion auf true gesetzt, fragt das SDK so lange ab, bis die Assembly einen Endzustand erreicht, was für einen kleinen ersten Testlauf praktisch, aber für lang laufende Request-Handler ungeeignet ist.
• Das Flag result markiert die Dateien eines Steps zur Aufnahme in das übergeordnete results-Objekt der Assembly. Es macht die Dateien nicht dauerhaft.
• Temporäre Assembly-Dateien sind standardmäßig etwa 24 Stunden lang und für eine begrenzte Anzahl von Abrufen verfügbar. Liefern Sie ihre URLs nicht direkt an Endnutzer aus; fügen Sie für nutzerseitig sichtbare Dateien einen Export-Robot hinzu.
• Die Assembly-ID ist eine nützliche private Referenz zur Fehlersuche, aber wer sie oder die Status-URL kennt, kann den Assembly Status ohne weitere Authentifizierung lesen. Halten Sie beide aus öffentlichen Logs und Client-Antworten heraus; verwenden Sie für diese Bereiche die eigene Auftragskennung Ihrer Anwendung.

Ein praxisnaher Ansatz

Wann Transloadit hilfreich ist

Verwenden Sie das Node-SDK, um eine Assembly mit /upload/handle und /image/resize zu erstellen. Das SDK signiert die Anfrage mit serverseitigen Zugangsdaten, lädt die lokale Datei hoch, wartet auf den Abschluss und gibt die Ergebnis-URL sowie die Assembly-ID zurück.

Architekturgrenze

Dieser Schnelleinstieg läuft auf einem vertrauenswürdigen Server und wartet, bis ein kleines Bild fertig verarbeitet ist. Eine Browser-Integration muss signierte, kurzlebige Parameter von einem Backend erhalten, während produktive Hintergrundarbeit einen verifizierten Webhook verwenden sollte, statt eine HTTP-Anfrage offen zu halten.