Transloadit

Was ist eine Assembly?

Eine Transloadit Assembly ist eine einzelne Ausführung von Assembly Instructions für Dateien, die hochgeladen, importiert oder vom Workflow selbst erzeugt werden. Jede Ausführung besitzt eine eindeutige assembly_id, die sie in späteren API-Anfragen identifiziert.

So funktionieren Assemblies

Eine Assembly ist der Workflow, der zur Laufzeit entsteht, wenn eine Anfrage Assembly Instructions mit Eingabequellen kombiniert: hochgeladene Dateien, Dateien, die Import-Steps abrufen, oder Dateien, die ein Robot selbst erzeugt, etwa einen Screenshot einer Website oder ein aus einem Textprompt erzeugtes Bild. Die Instructions werden inline als steps oder über template_id mit einem Verweis auf ein gespeichertes Template übermittelt; das Template speichert die Konfiguration, während die Assembly eine konkrete Ausführung davon ist. Steps starten, sobald die Steps, von denen sie abhängen, Dateien ausgeben. So kann eine Quelldatei mehrere Zweige versorgen, die parallel ausgeführt werden. Transloadit meldet den Verlauf über ein einziges Dokument mit dem Assembly Status. Dieses wird beim Erstellen der Assembly zurückgegeben, unter ihrer Status-URL bereitgestellt und an notify_url gesendet, sofern angegeben. Das Dokument ändert sich während des Uploads oder der Ausführung der Assembly; sobald die Ausführung einen Endzustand erreicht, enthält es entweder ok mit dem Endzustand oder error mit einem Fehlercode.

Wichtige Fakten

  1. Eine erfolgreiche HTTP-Antwort auf die Erstellungsanfrage bedeutet, dass die Assembly angenommen wurde, nicht, dass die Verarbeitung erfolgreich war. Die Assembly läuft noch, solange ok den Wert ASSEMBLY_UPLOADING, ASSEMBLY_EXECUTING oder ASSEMBLY_REPLAYING hat; nur ASSEMBLY_COMPLETED bedeutet Erfolg. ASSEMBLY_CANCELED und REQUEST_ABORTED erscheinen ebenfalls unter ok, ohne einen Erfolg anzuzeigen. Eine Statusanfrage kann HTTP 200 zurückgeben, während der Antwortkörper error enthält. Richten Sie Ihre Fallunterscheidung daher nach dem Antwortkörper und nicht nach dem HTTP-Status.
  2. assembly_id dient als Zugriffsberechtigung: Wer diesen Wert kennt, kann den Assembly Status einschließlich übermittelter Felder und Ergebnisse ohne weitere Authentifizierung abrufen. Halten Sie die ID und die Status-URLs aus öffentlichen Seiten und allen Inhalten heraus, die Sie mit nicht vertrauenswürdigen Dritten teilen. Die Option quiet verkürzt nur die Antwort auf die Erstellungsanfrage; sie schränkt nicht ein, wer den Status danach lesen kann.
  3. Das Erstellen einer Assembly ist nicht idempotent. Eine Wiederholung der Erstellungsanfrage, etwa nach einer Zeitüberschreitung, kann eine zweite Assembly mit einer eigenen assembly_id starten. Auch das Hinzufügen einer Signatur-Nonce verhindert das nicht. Deduplizieren Sie Wiederholungsversuche in Ihrer Anwendung.
  4. Ergebnisdateien werden unter dem Namen des Steps gruppiert, der sie erzeugt hat, nicht in der Upload-Reihenfolge. Ein Upload kann mehrere Ergebnisse liefern; ordnen Sie diese anhand von original_id den Uploads zu. Steps, die nur Dateien speichern, fügen keinen Eintrag hinzu, und nach einem Fehler können die Ergebnisse unvollständig sein. Ergebnis-URLs für Dateien in Transloadits temporärem Speicher laufen ab. Fügen Sie daher einen Export-Step hinzu, wenn die Dateien aufbewahrt werden müssen.

Wann Assemblies wichtig sind

Speichern Sie assembly_id auf Ihrem Server, wenn ein Workflow den Status per Polling abfragen, Ergebnisse abrufen oder eine eingehende Notification der auslösenden Anfrage zuordnen muss. Behandeln Sie diesen Wert als vertrauliche Zugangsinformation, da die ID allein ausreicht, um den Assembly Status zu lesen. Legen Sie vor dem Start fest, wie Ihre Anwendung den Ausgang ermittelt: durch Polling der Status-URL oder durch Festlegen von notify_url. Die Antwort auf die Erstellungsanfrage bestätigt nämlich nur, dass die Assembly angenommen wurde.

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