Transloadit

Was sind Assembly Instructions?

Transloadit Assembly Instructions definieren die benannten Steps eines Workflows zur Dateiverarbeitung. Jeder Step wählt einen Robot und dessen Parameter aus; der Parameter use bestimmt, wie hochgeladene, importierte oder erzeugte Dateien zwischen Steps weitergegeben werden.

So funktionieren Assembly Instructions

Instructions bilden einen gerichteten, azyklischen Verarbeitungsgraphen, der durch benannte Step-Konfigurationen und deren Eingabebeziehungen beschrieben wird. Jeder Step legt einen Robot und Parameter fest, während der Parameter use bestimmt, welche Uploads oder vorherigen Ergebnisse in diesen Step einfließen. Steps, die Dateien importieren oder erzeugen, können use weglassen, wenn sie nicht von einem früheren Step abhängen. Andere Steps ohne use werden implizit mit der Ausgabe des vorhergehenden Steps verbunden; beim zuerst deklarierten Step ist :original der Standardwert für use. Geben Sie use explizit an, wenn die Reihenfolge der Steps den Graphen nicht bestimmen soll. Der reservierte Step-Name :original steht für hochgeladene Dateien. Ein unter diesem Namen deklarierter Step darf nur den Robot /upload/handle ausführen, und kein anderer Step darf diesen Robot ausführen; ein Wert für use kann auf :original verweisen, ohne :original als Step zu deklarieren. Das Instructions-Dokument unterscheidet sich von einer Assembly, die eine einzelne Ausführung des Graphen ist, und von einem Template, das Instructions zur Wiederverwendung dauerhaft speichert. Bevor die Medienverarbeitung beginnt, prüft Transloadit, ob jeder Step ein korrekt aufgebautes Objekt ist, das einen vorhandenen Robot angibt, ob jeder deklarierte use-Verweis aufgelöst werden kann und ob der Graph frei von Zyklen ist.

Wichtige Fakten

  1. Step-Namen sind Bezeichner im Graphen. Wenn use einen Step angibt, der nicht existiert, lehnt Transloadit die Assembly vor Beginn der Verarbeitung mit ASSEMBLY_STEP_UNKNOWN_USE (HTTP 400) ab.
  2. Die Ergebnisse eines Steps können in mehrere spätere Steps einfließen, sodass nicht jedes daraus abgeleitete Ergebnis einen eigenen Upload oder Import benötigt. Diese Steps werden parallel ausgeführt, sobald ihr Eingabe-Step Dateien ausgibt. Bei expliziten Werten für use bestimmt die Reihenfolge, in der die Steps deklariert werden, daher nicht die Reihenfolge, in der Ergebnisse erzeugt oder exportiert werden. Die Deklarationsreihenfolge ist nur relevant, wenn ein Step use weglässt und implizit mit dem vorhergehenden Step verbunden wird.
  3. Ein Template hält wiederverwendbare Workflow-Logik aus Client-Anfragen heraus. Clients können Steps standardmäßig überschreiben; setzen Sie allow_steps_override im Template auf false, und Anfragen, die weiterhin Steps übergeben, werden mit TEMPLATE_DENIES_STEPS_OVERRIDE (HTTP 400) abgewiesen. Diese Einstellung betrifft nur Steps: Andere Anfrageparameter werden weiterhin mit dem Template zusammengeführt und überschreiben dessen Werte. Um zu verhindern, dass nicht vertrauenswürdige Aufrufer diese Parameter ändern, verlangen Sie Signature Authentication (über die Einstellung im Workspace oder require_signature_auth im Template) und lassen Sie ein vertrauenswürdiges Backend nur die Parameter signieren, die es freigibt. Diese Anforderung gilt für Anfragen, bei denen ein Auth Key zur Authentifizierung dient; gültige Bearer-Token umgehen sie. Eine Signatur deckt nur den serialisierten Wert von params ab. Upload-Formularfelder, die daneben gesendet werden, sind unsigniert, befüllen ${fields.*} und haben Vorrang vor gleichnamigen Werten im signierten Schlüssel fields. Ein gesperrtes Template, das einen Speicherpfad oder eine andere Einstellung aus ${fields.*} bildet, lässt den Aufrufer diesen Wert daher weiterhin bestimmen.
  4. Ein Step, der nichts erzeugt, ist nicht zwangsläufig fehlgeschlagen. Standardmäßig ignoriert ein Robot Dateitypen, die er nicht verarbeitet (als Beispiel nennt die Dokumentation /video/encode, der Bilder ignoriert). Ein Zweig kann für solche Dateien daher einfach nichts erzeugen. Nutzen Sie /file/filter, um gemischte Uploads gezielt weiterzuleiten; die Dokumentation sieht force_accept nur für die Fehlersuche und Sonderfälle vor.

Wann Assembly Instructions wichtig sind

Speichern Sie Instructions in einem Template, wenn Aufrufer einen serverseitig verwalteten Workflow wiederverwenden sollen. Wenn Aufrufer dessen Steps nicht ändern dürfen, setzen Sie allow_steps_override auf false. Um auch Änderungen an anderen Anfrageparametern zu verhindern, verlangen Sie Signature Authentication für Anfragen, bei denen Ihr Auth Key zur Authentifizierung dient. Keine der beiden Maßnahmen deckt Upload-Formularfelder ab. Leiten Sie daher keine Einstellung, die Aufrufer nicht selbst bestimmen dürfen, aus ${fields.*} ab. Prüfen Sie beim Generieren von Instructions oder Umbenennen von Steps, dass jeder Wert für use auf einen deklarierten Step-Namen oder :original verweist, damit die Assembly die Validierung besteht.

So hilft Transloadit bei Assembly Instructions

Transloadit validiert Assembly Instructions und führt sie als Workflow für eine Assembly aus. Jeder benannte Step ruft einen Robot auf, um Dateien hochzuladen, zu importieren, zu verarbeiten, zu analysieren, zu speichern oder auszuliefern. Der Parameter use leitet Ergebnisse zwischen Steps weiter. Ein Template speichert Instructions zur Wiederverwendung, eine Assembly ist eine einzelne Ausführung dieser Instructions, und Assembly Status und Notifications melden das Ergebnis.

Entdecken Sie die Plattformfunktionen von Transloadit

Quellen

Machen Sie aus Medienwissen eine funktionierende Pipeline

Verbinden Sie Uploads, Verarbeitung, KI, Storage und Auslieferung über eine deklarative API – um Encoding-Stack, Skalierung und ständig wechselnde Formate müssen Sie sich nicht selbst kümmern.

Transloadit kostenlos ausprobieren