Workflow-Automatisierung # Anpassbare Medienverarbeitungs-Workflows mit Transloadit Entwerfen Sie ein wiederverwendbares Template mit Validierung, Variablen, parallelen Derivaten, sicherem Speicher und beobachtbarem Abschluss. Veröffentlicht am 26. August 2026 ## Wichtigste Erkenntnisse * Modellieren Sie den Workflow als Graphen, dessen `use`-Beziehungen die Reihenfolge explizit machen. * Bewahren Sie stabile Verarbeitungsrichtlinien in einem gespeicherten Template auf und geben Sie nur validierte Felder frei. * Führen Sie unabhängige Derivate parallel aus. Steps pro Datei verarbeiten jede Datei, die von den vorgelagerten Steps ausgegeben wird, die sie lesen; nur Merge- oder Bündelungs-Steps warten auf einen vollständigen Satz. Ein anpassbarer Workflow sollte die wenigen Werte offenlegen, die sich pro Auftrag legitim ändern, und dabei seinen Verarbeitungsgraphen kontrolliert halten. Transloadits Assembly Instructions drücken diesen Graphen als benannte Steps aus, und ein gespeichertes Template ermöglicht es einer Anwendung, ihn wiederholt auszuführen, ohne Speicher-Zugangsdaten oder Transformationsrichtlinien erneut zu senden. ## In diesem Leitfaden 1. [Abhängigkeiten zeichnen, bevor JSON geschrieben wird](#customizable-media-processing-workflows-section-1) 2. [Feste Richtlinien von Laufzeitfeldern trennen](#customizable-media-processing-workflows-section-2) 3. [Eingaben vor aufwendiger Verarbeitung validieren](#customizable-media-processing-workflows-section-3) 4. [Mit rotierbaren Zugangsdaten und Pfaden exportieren](#customizable-media-processing-workflows-section-4) 5. [Jeden Lauf als asynchrone Zustandsmaschine betreiben](#customizable-media-processing-workflows-section-5) 6. [Änderungen mit repräsentativen Testdaten prüfen](#customizable-media-processing-workflows-section-6) ## Worauf es besonders ankommt * Verweisen Sie auf gespeicherte Template-Zugangsdaten, statt Cloud-Geheimnisse in Assembly Instructions zu hinterlegen. * Erfassen Sie für jeden Durchlauf die Template-ID, das Anwendungs-Workflow-Label, die Assembly-ID, die Eingaben und das abschließende Ergebnis. ## Abhängigkeiten zeichnen, bevor JSON geschrieben wird Beginnen Sie mit Dateien und Entscheidungen, nicht mit Robot-Namen. Identifizieren Sie die Dateien und Derivate, die der Workflow erzeugt, die Validierungsrichtlinien, die er durchsetzt, die Ziele, in die er schreibt, und die Fehlerfälle, die das Produkt behandeln muss, etwa abgelehnte Eingaben oder einen fehlgeschlagenen Export. Geben Sie dann jeder Operation einen Step-Namen, der ihr Ergebnis beschreibt. In den Assembly Instructions erzeugt der Wert `use` die Kante zwischen einem vorgelagerten Step und dessen Abnehmer; die Reihenfolge der Schlüssel im JSON-Objekt legt keine Ausführungsreihenfolge fest. Unabhängige Steps können dieselbe vorgelagerte Datei lesen und gleichzeitig laufen. Zwei Resize-Steps, die beide aus einem gemeinsamen Filter-Step schöpfen, warten nicht aufeinander; jeder beginnt, sobald der Filter-Step eine Datei ausgibt. Das konkrete JSON für diese Struktur zeigt der nächste Abschnitt. Jedes Derivat wird in ein eigenes Präfix exportiert, sodass die parallelen Varianten sich nie einen Schlüssel teilen. Ein Merge-Robot ist anders: Er benötigt unter Umständen ein gebündeltes Set benannter Eingaben, bevor er etwas erzeugen kann. Modellieren Sie diese Abhängigkeit explizit, statt sich auf die scheinbare JSON-Reihenfolge zu verlassen. ### Knoten sind Steps Jeder benannte Step ruft einen Robot mit einer begrenzten Menge an Parametern auf. ### Kanten entstehen durch use Die deklarierte vorgelagerte Eingabe bestimmt Bereitschaft und Datenfluss. ### Zweige können sich überschneiden Derivate, die sich eine Eingabe teilen, können unabhängig voneinander laufen, statt zu einer seriellen Kette zu werden. ## Feste Richtlinien von Laufzeitfeldern trennen Halten Sie Validierung, zulässige Robots, Ausgaberollen und Ziele in einem gespeicherten Template fest. Werte, die tatsächlich von Anfrage zu Anfrage variieren, können als Felder eintreffen und über `${fields.*}`-Variablen referenziert werden. Eine Mandanten-ID, ein angefordertes Variantenprofil oder eine stabile Asset-ID sind vertretbar; ein beliebiger Robot-Name, Ziel-Zugangsdaten oder eine unbeschränkte Ausgabedimension in der Regel nicht. Setzen Sie `allow_steps_override` im Template auf false, wenn ein nicht vertrauenswürdiger Aufrufer keine neuen Steps in den gespeicherten Graphen einfügen darf. Diese Einstellung schützt den Graphen, nicht die Bedeutung jedes Feldes. Validieren Sie Felder in der Anwendung, bevor Sie die Assembly erstellen: Autorisieren Sie den Mandanten, akzeptieren Sie nur bekannte Profile, begrenzen Sie numerische Bereiche und lehnen Sie unbekannte Schlüssel ab. Das Template sollte außerdem sichere Standardwerte oder Filter verwenden, wo ein fehlerhafter Wert übermäßigen Aufwand verursachen könnte. Das vollständige Template unten enthält Eingabevalidierung, Export- und Benachrichtigungsparameter, die die folgenden Abschnitte erklären. Ein gesperrter, parametrisierter Bildworkflow ``` { "allow_steps_override": false, "max_number_of_files": 1, "max_size": 52428800, "notify_url": "https://app.example.com/webhooks/transloadit", "steps": { ":original": { "robot": "/upload/handle" }, "accepted_images": { "use": ":original", "robot": "/file/filter", "accepts": [ ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp|image/avif)$"] ], "error_on_decline": true, "error_msg": "Upload a JPEG, PNG, WebP, or AVIF image." }, "web_image": { "use": "accepted_images", "robot": "/image/resize", "width": 1600, "height": 1200, "resize_strategy": "fit", "format": "webp" }, "thumbnail": { "use": "accepted_images", "robot": "/image/resize", "width": 320, "height": 320, "resize_strategy": "fillcrop", "format": "webp" }, "export_web": { "use": "web_image", "robot": "/s3/store", "acl": "private", "credentials": "media-output", "path": "${fields.tenant_id}/${assembly.id}/web/${unique_prefix}/${file.url_name}" }, "export_thumb": { "use": "thumbnail", "robot": "/s3/store", "acl": "private", "credentials": "media-output", "path": "${fields.tenant_id}/${assembly.id}/thumb/${unique_prefix}/${file.url_name}" } } } ``` Das gespeicherte Template mit validierten Feldern ausführen ``` // Illustrative fragment: these objects come from your application, not the SDK. const assembly = await transloadit.createAssembly({ files: { image: inputPath }, params: { template_id: process.env.TRANSLOADIT_TEMPLATE_ID, fields: { tenant_id: tenant.id, }, }, }) await jobs.attachAssembly({ jobId: job.id, assemblyId: assembly.assembly_id, }) ``` ### Stabile Richtlinie Robot-Auswahl, Validierung, Exportziele und Ergebnisrollen gehören in eine kontrollierte Konfiguration. ### Begrenzte Variation Felder legen einen kleinen Vertrag offen, statt den gesamten Graphen dem Aufrufer zu überlassen. ### Zwei Validierungsebenen Autorisierung in der Anwendung und Schutzmaßnahmen im Template adressieren unterschiedliche Fehler- und Missbrauchspfade. ## Eingaben vor aufwendiger Verarbeitung validieren Setzen Sie günstige, deterministische Prüfungen vor die Erzeugung von Derivaten. Auf Assembly- und Template-Ebene begrenzt `max_size` die Gesamtgröße des kompletten Uploads – der gesamte Upload wird abgebrochen, wenn die Summe diesen Wert überschreitet, selbst wenn jede einzelne Datei darunter liegt – und `max_number_of_files` begrenzt, wie viele Dateien die Anfrage enthalten darf. Für eine Größenbegrenzung pro Datei verwenden Sie `/file/filter` auf `${file.size}`; der Filter wertet jede Datei einzeln aus und kann auch den serverseitig erkannten MIME-Typ sowie extrahierte Metadaten prüfen. Wenn nicht unterstützte Eingaben die gesamte Verarbeitung fehlschlagen lassen sollen, setzen Sie `error_on_decline` und geben Sie eine Meldung an, die dem Nutzer sagt, was er ändern muss. Das Beispiel begrenzt den Durchlauf bewusst auf eine hochgeladene Datei. Eine höhere `max_number_of_files`-Angabe macht das Ablehnungsverhalten bei mehreren Dateien relevant. Bevorzugen Sie eine explizite Positivliste wie JPEG, PNG, WebP und AVIF, wenn die nachgelagerte Operation nur Browserbilder unterstützt. Eine breite `image/*`-Regel akzeptiert Formate, die das Ziel möglicherweise nicht darstellen kann, während Dateierweiterung und vom Browser gemeldeter MIME-Wert nur Angaben des Clients sind. Entscheiden Sie separat, ob eine abgelehnte Datei eine gesamte Mehrdatei-Assembly scheitern lässt, einfach aus einem Zweig verschwindet oder in einen anderen Zweig übergeht; das sind Produktverhalten, keine beiläufigen Filtereinstellungen. ### Günstige Prüfungen an erster Stelle Ungeeignete Eingaben werden abgelehnt, bevor kostenpflichtige oder langsame Transformationen beginnen. ### Serverseitig erkannte Eigenschaften Verwenden Sie extrahierte MIME-Angaben und Metadaten, statt sich allein auf die Dateierweiterung zu verlassen. ### Explizites Ablehnungsverhalten Legen Sie fest, ob eine abgelehnte Datei den gesamten Auftrag beendet oder nur den Durchfluss durch einen Zweig stoppt. ## Mit rotierbaren Zugangsdaten und Pfaden exportieren Erstellen Sie Template-Zugangsdaten für das Speicherziel und verweisen Sie aus dem Export-Robot auf ihren Namen. Die Assembly Instructions enthalten dann ein stabiles Zugangsdaten-Label statt eines Zugriffsschlüssels und eines Secrets. Das Rotieren der gespeicherten Zugangsdaten aktualisiert künftige Läufe, ohne ein neues Secret in den Quellcode, Browser-Parameter oder jedes Template zu kopieren, das sie verwendet. `/s3/store` setzt `acl` standardmäßig auf `public-read`, setzen Sie es also auf `private`, sofern die exportierten Dateien nicht öffentlich lesbar sein sollen. Erstellen Sie Zielpfade aus validierten Mandanten- oder Asset-Kennungen, der Assembly-ID, der Variantenrolle und Transloadits plattformseitig erzeugtem `${unique_prefix}`. Dieses eindeutige, 33 Zeichen lange Präfix pro Datei enthält einen Schrägstrich und erweitert sich damit im Speicherschlüssel zu einem zweistufigen Unterverzeichnis, wodurch gleichnamige Eingaben innerhalb einer Assembly nicht kollidieren. Geben Sie jedem parallelen Derivat ein eigenes Variantenrollen-Pfadsegment, etwa `web/` oder `thumb/`, damit deren Exporte niemals auf demselben Schlüssel kollidieren. Verwenden Sie keinen unbereinigten Upload-Dateinamen als einzigen Schlüssel, und entscheiden Sie, was ein Wiederholungsversuch tun soll, wenn das Objekt bereits existiert. Ein idempotenter Export schreibt entweder dasselbe beabsichtigte Objekt oder prüft und gleicht das Ziel ab, bevor ein weiteres erstellt wird. Erfassen Sie für jedes Ergebnis den endgültigen Speicherschlüssel, damit Löschung und Ersetzung später alle Kopien finden können. ### Zugangsdaten-Bezeichnung Trennt die Rotation von Geheimnissen vom Workflow-JSON, das darauf verweist. ### Stabile Pfadeingaben Mandanten-, Asset-, Assembly- und Variantenkennungen machen Ausgaben nachvollziehbar. ### Überschreibungsvertrag Legen Sie fest, ob ein bestehender Zielschlüssel ersetzt, abgelehnt, versioniert oder abgeglichen wird. ## Jeden Lauf als asynchrone Zustandsmaschine betreiben Speichern Sie einen Auftragsdatensatz der Anwendung, bevor Sie die Assembly starten. Erfassen Sie den Akteur, den Mandanten, die Kennung der Eingabedatei, die Template-ID, die validierten Felder, das Anwendungs-Workflow-Label und einen stabilen Vorgangsschlüssel. Das Anwendungs-Workflow-Label und der Vorgangsschlüssel sind rein lokale Kennungen, die in Ihrer eigenen Datenbank gespeichert werden; sie werden nie an Transloadit gesendet. Fügen Sie die Assembly-ID hinzu, sobald sie zurückgegeben wird. Dieser Datensatz ermöglicht es, bei Wiederholungsversuchen zu prüfen, ob eine äquivalente Arbeit bereits aktiv oder abgeschlossen ist, statt nach einem Timeout einen zweiten Export zu erzeugen. Konfigurieren Sie `notify_url`, wenn der Auftrag im Hintergrund abgeschlossen werden soll; setzen Sie sie wie im obigen Template gezeigt im gespeicherten Template, damit jeder Lauf sie erbt. Prüfen Sie die Benachrichtigungssignatur mit dem Auth Secret, das zu dem Auth Key gehört, der für diese Assembly verwendet wurde, geben Sie bei einer gültigen Zustellung umgehend HTTP 200 zurück und verarbeiten Sie Duplikate idempotent. Ein regelmäßiger Abgleichsauftrag sollte lokal aktive Arbeit mit Assembly Status vergleichen, damit ein verlorener Callback keinen Datensatz verwaisen lässt. Überwachen Sie Latenz, Fehlerklasse, verarbeitete Bytes, Ausgaben und Webhook-Wiederholungen anhand des Anwendungs-Workflow-Labels. ### Vorgangsschlüssel Verhindert, dass ein Wiederholungsversuch des Aufrufers stillschweigend doppelte Verarbeitung und Exporte erzeugt. ### Verifizierter Webhook Authentifiziert Abschlussdaten und erlaubt gleichzeitig, dass die ursprüngliche Anfrage schnell endet. ### Abgleich Repariert den lokalen Zustand, wenn Benachrichtigungen verzögert, doppelt oder gar nicht eintreffen. ## Änderungen mit repräsentativen Testdaten prüfen Ein Workflow ist nur so stabil wie die Eingaben, mit denen er getestet wird. Halten Sie kleine Testdaten für jedes akzeptierte Format, Grenzabmessungen, Transparenz, Ausrichtung, Animation, übergroße Eingaben und einen explizit abgelehnten Typ bereit. Prüfen Sie Ausgaberolle, Format, Abmessungen, Speicherpfad und Endzustand, statt nur zu kontrollieren, dass die Assembly abgeschlossen wurde. Fügen Sie einen Zielfehler und eine doppelte Benachrichtigung hinzu, damit der Wiederherstellungspfad vor einem Vorfall durchlaufen wird. Halten Sie das beabsichtigte Verhalten in der Anwendungskonfiguration oder Versionsverwaltung fest und verknüpfen Sie diese Bezeichnung mit jedem Lauf. Wenn sich das gespeicherte Template ändert, testen Sie es in einem Nichtproduktions-Workspace oder mit isolierten Zielen, prüfen Sie Kosten und Metadaten und leiten Sie zunächst nur einen begrenzten Anteil des Traffics um. Verschlechtern sich die Ergebnisse, führen Sie neue Arbeit zurück zum vorherigen kontrollierten Verhalten und gleichen Sie bereits laufende Assemblies ab, statt anzunehmen, dass sie gestoppt wurden. ### Formatmatrix Deckt die Eingaben und Metadatenvarianten ab, die das Produkt zu akzeptieren verspricht. ### Testdaten für Fehlerfälle Belegen Sie neben Erfolg auch Ablehnung, Exportfehler, doppelte Zustellung und Wiederholungsverhalten. ### Begrenzter Rollout Begrenzt Kosten und Auswirkungen auf Kunden, während ein geänderter Workflow unter echtem Traffic gemessen wird. ## Wissenswerte technische Details * Ein dateibezogener Step beginnt, sobald ein vorgelagerter Step, der in seinem `use`-Wert genannt wird, eine Datei ausgibt; nur Merge- oder Bündelungs-Robots warten auf einen vollständigen Satz benannter Eingaben. Die Position eines Steps im JSON-Objekt bestimmt nicht die Ausführungsreihenfolge. * Assembly Variables wie `${fields.tenant_id}`, `${assembly.id}` und `${file.url_name}` – eine URL-sichere (per URL-Slug erzeugte) Version des Dateinamens der aktuellen Step-Datei einschließlich ihrer Dateierweiterung – werden zur Ausführungszeit aufgelöst und können Dimensionen, Pfade und andere Robot-Parameter-Werte parametrisieren. In den Beispiel-Exportpfaden sorgt `${assembly.id}` für Eindeutigkeit je Lauf, und das slashhaltige `${unique_prefix}` hält Dateien innerhalb eines Laufs unterscheidbar. * Wenn `allow_steps_override` in einem gespeicherten Template auf false gesetzt ist, können Aufrufer keine Ersatz-Steps in dieses Template einfügen. Laufzeitfelder benötigen weiterhin eine anwendungsseitige Validierung und Autorisierung. * /file/filter kann serverseitig erkannte Dateieigenschaften mit Array-Bedingungen vergleichen. Eine spezifische MIME-Positivliste ist sicherer, als sich auf eine Dateierweiterung oder einen vom Client gemeldeten Typ zu verlassen. * Template-Zugangsdaten halten Zielgeheimnisse getrennt vom Template-JSON und können aktualisiert werden, ohne Schlüssel in jede Integration zu kopieren. * Assembly Notifications werden erneut zugestellt, wenn der Empfänger nicht mit HTTP 200 antwortet. Konsumenten müssen die Signatur prüfen und doppelte, verzögerte oder nicht in Reihenfolge eintreffende Zustellungen tolerieren. ## Ein praxisnaher Ansatz 1. 1\ Zeichnen Sie die erforderlichen Eingaben, Derivate, Steps, die aus mehreren Derivaten lesen, Exporte und Fehlergrenzen auf. 2. 2\ Speichern und sperren Sie ein Template, dessen variable Eingaben bewusst begrenzt sind. 3. 3\ Reichen Sie eine repräsentative Datei ein und prüfen Sie jeden Step im Assembly Status. 4. 4\ Fügen Sie verifizierte Webhook-Verarbeitung, idempotente Persistenz, Testdaten und einen kontrollierten Rollout hinzu. Ein vierstufiger Medienworkflow ## Wann Transloadit hilfreich ist Verwenden Sie ein gespeichertes Template, um /upload/handle, /file/filter, parallele /image/resize-Steps und /s3/store zu verbinden. Sperren Sie den Verarbeitungsgraphen, indem Sie allow\_steps\_override auf false setzen, übergeben Sie zur Laufzeit begrenzte Felder und gleichen Sie den Abschluss über Assembly Status und verifizierte Webhooks ab. ## Architekturgrenze Assembly Templates beschreiben die Verarbeitung und Bewegung von Dateien. Sie besitzen weder Produktfreigaben noch Mandantenautorisierung, Geschäftszustand oder die Konfigurationshistorie einer Anwendung; diese Entscheidungen bleiben in dem System, das jeden Auftrag startet und protokolliert. ## Häufig gestellte Fragen ### Steuert die Reihenfolge der Steps im JSON die Ausführung? Nein. Die `use`-Abhängigkeiten bestimmen, wann ein Step ausgeführt werden kann. Unabhängige Steps können parallel laufen, auch wenn einer im Objekt später erscheint. ### Kann ein gesperrtes Template weiterhin benutzerdefinierte Werte annehmen? Ja. `allow_steps_override: false` verhindert, dass Aufrufende die verarbeitenden Steps ersetzen. Die Anwendung kann weiterhin Felder senden, die von `${fields.*}`-Variablen verwendet werden, muss diese Werte jedoch validieren und autorisieren. ### Sollten Cloud-Speicherschlüssel in Assembly Instructions erscheinen? Nein. Speichern Sie sie als Template-Zugangsdaten und verweisen Sie aus dem Speicher-Robot auf den Namen der Zugangsdaten. So bleiben Geheimnisse aus dem Workflow-JSON heraus, und die Rotation erfolgt unabhängig davon. ### Wie sollte ein Workflow sicher geändert werden? Bewahren Sie das Anwendungs-Workflow-Label und die Konfigurationshistorie in Ihrem eigenen System auf, testen Sie Änderungen mit repräsentativen Testdaten und verlagern Sie den Traffic gezielt. Bewahren Sie zu jedem Vorgang genügend Informationen auf, um zu erklären, welches Verhalten seine Ergebnisse erzeugt hat. ### Was passiert, wenn ein Webhook doppelt zugestellt wird? Behandeln Sie eine doppelte Zustellung als Normalfall. Verifizieren Sie die Signatur, schlagen Sie die Assembly oder den Vorgangsschlüssel nach und gestalten Sie dieselbe abschließende Aktualisierung so, dass sie sich gefahrlos erneut anwenden lässt, ohne Assets oder für Nutzer sichtbare Ereignisse zu duplizieren. ## Erstellen Sie den Workflow Entwickeln Sie das Konzept mithilfe der Robot-Dokumentation und funktionsfähiger Demos zu einer getesteten Assembly weiter. ### Relevante Robots * [/upload/handle](/de/docs/robots/upload-handle.md) * [/file/filter](/de/docs/robots/file-filter.md) * [/image/resize](/de/docs/robots/image-resize.md) * [/s3/store](/de/docs/robots/s3-store.md) * [Assembly Instructions verstehen](/de/docs/topics/assembly-instructions.md) * [Ein Template erstellen und sperren](/de/docs/topics/templates.md) * [Assembly Variables verwenden](/de/docs/topics/assembly-variables.md) * [Verifizierte Webhooks verarbeiten](/de/docs/topics/webhooks.md) * [Lesen Sie die API-Dokumentation](/de/docs.md) * [Entdecken Sie funktionsfähige Demos EN (English)](/demos.md) * [Kostenlosen Workspace erstellen](/c/signup/) Workflow-Automatisierung ## Mit verwandten Leitfäden fortfahren * [Transloadit in fünf Minuten integrieren](/de/guides/transloadit-five-minute-integration.md)\ Installieren Sie das Node-SDK, skalieren Sie ein Bild und prüfen Sie in etwa fünf Minuten ein reales Assembly-Ergebnis. * [Medienautomatisierung: vom Upload zur zuverlässigen Ausgabe](/de/guides/media-automation.md)\ Automatisieren Sie wiederholbare Medienaufnahme, Transformation, Validierung und Export, ohne Beobachtbarkeit und Kontrolle einzuschränken. * [Vollständiger Leitfaden für Digital-Asset-Workflows](/de/guides/digital-asset-workflows.md)\ Gestalten Sie einen Digital-Asset-Workflow von Aufnahme und Verarbeitung über Prüfung und Veröffentlichung bis zu Aufbewahrung und Löschung. * [KI-Inhaltsmoderation in einem Upload-Workflow](/de/guides/ai-content-moderation-workflows.md)\ Integrieren Sie KI-Moderation mit Konfidenzschwellen und menschlicher Prüfung in einen kontrollierten Upload-Workflow. * [Automatisierte Inhaltsmoderation: Aufbau und Fehlerbehandlung](/de/guides/automated-content-moderation.md)\ Erstellen Sie automatisierte Moderation als mehrschichtiges System aus Dateiprüfungen, Klassifikatoren, Richtlinienentscheidungen und Prüfwarteschlangen. * [Automatisierte Bildanalyse mit beobachtbaren Workflows](/de/guides/automated-image-analysis.md)\ Gestalten Sie die Bildanalyse als wiederholbaren, asynchronen Workflow statt als blockierende Anfrage Ihrer Anwendung.