Transloadit

Assembly Variables

Transloadit unterstützt Variablen innerhalb Ihrer Assemblies, mit denen Sie leistungsfähigere Workflows erstellen können. Sie können beispielsweise Dateien anhand von width filtern, den Speicherort anhand von type beeinflussen und vieles mehr. Wir haben eine vollständige Liste der Platzhaltervariablen für Assembly Variables zusammengestellt. Sie können in jedem Parameterwert von jedem Robot verwendet werden.

  • ${assembly.id} — Die ID der Assembly für den aktuellen Upload. Sie ist eine UUIDv4 ohne Bindestriche.

  • ${assembly.region} — Die AWS-Region, in der die Assembly verarbeitet wird. Damit können Sie Dateien aus einem Bucket in derselben Region importieren, um Kosten und Latenzen bei der Datenübertragung zu reduzieren.

  • ${assembly.parent_id} — Die ID der übergeordneten Assembly, wenn diese Assembly erneut ausgeführt wird.

  • ${unique_prefix} — Ein eindeutiges Präfix mit 33 Zeichen, das Dateinamenkonflikte verhindert, beispielsweise "f2/d3eeeb67479f11f8b091b04f6181ad".

    Beachten Sie den / im Präfix. Wenn Sie ${unique_prefix} beispielsweise im Parameter path von 🤖/s3/store verwenden, werden Unterverzeichnisse in Ihrem S3-Bucket erstellt. Dies kann erwünscht sein oder nicht. Verwenden Sie ${file.id}, wenn Sie ein eindeutiges Präfix ohne Schrägstriche benötigen.

  • ${unique_original_prefix} — Diese Variable ähnelt ${unique_prefix}. Der Unterschied besteht darin, dass zwei verschiedene Encoding-Ergebnisse derselben hochgeladenen Datei (der Originaldatei) hier dasselbe Präfix erhalten.

  • ${previous_step.name} — Der Name von dem vorherigen Step, der die aktuelle Datei erzeugt hat.

  • ${file.id} — Die ID der verarbeiteten Datei. Sie ist eine UUIDv4 ohne Bindestriche.

  • ${file.original_id} — Die ID der Originaldatei, von der eine bestimmte Datei abgeleitet wurde. Wenn Sie beispielsweise Dateien mit einem Import-Robot importieren und anschließend auf beliebige Weise codieren, enthalten die Encoding-Ergebnisdateien eine ${file.original_id}, die der ${file.id} der importierten Datei entspricht.

  • ${file.original_name} — Der Name einschließlich Dateierweiterung der Originaldatei, von der eine bestimmte Datei abgeleitet wurde. Wenn Sie beispielsweise Dateien mit einem Import-Robot importieren und anschließend auf beliebige Weise codieren, enthalten die Encoding-Ergebnisdateien einen ${file.original_name}, der dem ${file.name} der importierten Datei entspricht.

  • ${file.original_basename} — Der Basisname der Originaldatei, von der eine bestimmte Datei abgeleitet wurde. Wenn Sie beispielsweise Dateien mit einem Import-Robot importieren und anschließend auf beliebige Weise codieren, enthalten die Encoding-Ergebnisdateien einen ${file.original_basename}, der dem ${file.basename} der importierten Datei entspricht.

  • ${file.original_path} — Der Importpfad der Originaldatei, von der eine bestimmte Datei abgeleitet wurde. Alle unsere Import-Robots setzen ${file.original_path} entsprechend.

    Wenn Sie beispielsweise 🤖/s3/import verwenden, um Dateien aus Amazon S3 zu importieren, besitzen sowohl die importierten Dateien als auch alle davon abgeleiteten Dateien einen Wert für file.original_path, der dem Pfad zur Datei auf S3 entspricht, jedoch ohne den Dateinamen. Lautete der S3-Pfad also "path/to/file.txt", ist file.original_path gleich "/path/to/". Lautete der Pfad "/a.txt", ist ${file.original_path} gleich "/".

    file.original_path enthält immer genügend Schrägstriche, damit Sie den Wert sicher im Parameter path Ihres Export-Steps verwenden können, beispielsweise so: "path": "${file.original_path}${file.name}". Dies ist praktisch, wenn Sie Dateien zum Beispiel aus S3 importieren, auf beliebige Weise konvertieren und anschließend mit derselben oder einer ähnlichen Dateistruktur wieder auf S3 speichern möchten.

  • ${file.name} — Der Name einschließlich Dateierweiterung der verarbeiteten Datei.

  • ${file.url_name} — Der als Slug formatierte Name der Datei.

    Dateinamen werden transliteriert und bereinigt, um eine URL-sichere Version zu erzeugen. Nichtlateinische Zeichen werden in lateinische Entsprechungen umgewandelt (z. B. café.jpg → cafe.jpg, бубу.mov → bubu.mov), während Leerzeichen oder Satzzeichen durch Bindestriche ersetzt werden. Aufeinanderfolgende nicht eindeutige Zeichen können zu einem einzelnen Bindestrich zusammengefasst werden.

  • ${file.basename} — Der Name ohne Dateierweiterung der verarbeiteten Datei. Damit können Sie Aktionen dynamisch pro Datei statt pro Assembly mit fields ausführen.

  • ${file.url_basename} — Der als Slug formatierte Basisname der Datei (der Dateiname ohne Dateierweiterung).

    Dateinamen werden transliteriert und bereinigt, um eine URL-sichere Version zu erzeugen. Nichtlateinische Zeichen werden in lateinische Entsprechungen umgewandelt (z. B. café.jpg → cafe.jpg, бубу.mov → bubu.mov), während Leerzeichen oder Satzzeichen durch Bindestriche ersetzt werden. Aufeinanderfolgende nicht eindeutige Zeichen können zu einem einzelnen Bindestrich zusammengefasst werden.

  • ${file.user_meta.*} — Benutzerdefinierte Metadaten je Datei aus tus-Uploads oder Robot-Anweisungen. Siehe Benutzerdefinierte Metadaten für Vererbungsregeln und ein vollständiges Beispiel.

  • ${file.ext} — Die Dateierweiterung.

  • ${file.size} — Die Dateigröße in Byte.

  • ${file.type} — Eine grobe, von Transloadit erkannte Dateikategorie, die im Assembly Status JSON bereitgestellt wird, beispielsweise image, video, audio, pdf, office, xls, swf oder document. Verwenden Sie diese Variable, wenn Sie eine grobe Kategorie oder Kompatibilität mit bestehenden Workflows benötigen. Für zuverlässige Inhaltsprüfungen empfiehlt sich ${file.mime}.

  • ${file.mime} — Der von Transloadit erkannte MIME-Typ der Datei, üblicherweise während der serverseitigen Metadatenextraktion im normalen Upload-Ablauf. Er kann vom MIME-Typ abweichen, den der Client oder Browser ursprünglich gemeldet hat. Verwenden Sie diese Variable vorzugsweise für inhaltsabhängige Verzweigungen und nach Möglichkeit MIME-Familien wie image/*, video/* oder audio/*.

  • ${file.md5hash} — Der MD5-Hash der Datei. Dieser Hash basiert auf dem Dateiinhalt und nicht nur auf dem Dateinamen.

  • ${file.*} — Jede Dateieigenschaft, die im endgültigen Ergebnis-Array verfügbar ist, beispielsweise ${file.meta.width}. Nicht alle Metadatenschlüssel sind für alle Dateitypen verfügbar.

  • ${fields.*} — Die zusammen mit dem Upload übermittelten Felder.

    Wenn beispielsweise bei einer Formularübermittlung Uppy so konfiguriert wurde, dass fields: ['myvar'] zulässig ist, und das Formular ein Tag wie <input type="hidden" name="myvar" value="1" /> enthielt, würde ${fields.myvar} den Wert 1 enthalten.

    Alternativ können Felder auch wie folgt programmgesteuert befüllt werden:

    {
  "steps": {
    "store": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${assembly.id}/${fields.subdir}/356"
    }
  },
  "fields": {
    "subdir": "bar"
  }
}

    Bei einem Konflikt haben Variablen aus Formularfeldern Vorrang vor Variablen aus dem Schlüssel fields.

    Smart-CDN-Anfragen befüllen denselben Namensraum stattdessen aus der URL. Abfrageparameter werden zu ${fields.*}-Werten. Der Pfad nach dem Template-Namen wird ohne führenden Schrägstrich zum impliziten Wert ${fields.input}. So liefert https://my-app.tlcdn.com/image-template/images/canoe.jpg?w=640 für ${fields.input} den Wert images/canoe.jpg und für ${fields.w} den Wert 640. Wird ${fields.input} als path für 🤖/s3/import verwendet, liest der Robot daher den Objektschlüssel images/canoe.jpg. Diese URL-basierte Befüllung unterscheidet sich von Formularfeldern beim Upload und dem oben beschriebenen Assembly-Schlüssel fields.

  • ${browser.wanted_image_format} — Das vom Accept-Header des anfragenden Clients bevorzugte Bildformat. Die Variable wird zu dem Format aus "avif", "webp" und "jpg" mit der höchsten positiven Qualitätsgewichtung (q). Bei gleicher Gewichtung gilt diese Reihenfolge. Platzhalter wie */* und image/* wählen AVIF oder WebP nicht aus. Ein fehlender, leerer oder ausschließlich aus Platzhaltern bestehender Header ergibt "jpg". JPEG ist ebenfalls ein vollwertiger Kandidat: image/avif;q=0.2,image/jpeg;q=1 ergibt deshalb "jpg".

    Die Variable steht auch in regulären Assemblies zur Verfügung. SDK- und API-Anfragen ohne aussagekräftigen Accept-Header verwenden häufig den Rückfallwert "jpg". Ein Smart-CDN-Edge kann stattdessen den vertrauenswürdigen, vorab normalisierten Header x-tl-image-format setzen. Dieser wird ohne erneute Auswertung von "avif" in denselben Wert "webp", "jpg" oder Accept aufgelöst.

    Der Rückfallwert "jpg" beschreibt die Client-Unterstützung und nicht die Eingabedatei. Ordnen Sie diesen Rückfallwert bei 🤖/image/resize null zu, damit Clients ohne ausdrückliche Präferenz für ein modernes Format das Eingabeformat erhalten. So bleiben Transparenz und Animation erhalten, statt die Eingabe unnötig als JPEG neu zu kodieren.

  • ${Date.now()} — Das aktuelle Datum und die aktuelle Uhrzeit als Anzahl der Millisekunden seit Beginn der UNIX-Epoche, die als Mitternacht zu Beginn des 1. Januar 1970 UTC definiert ist. Technisch gesehen handelt es sich nicht um eine Variable. Stattdessen wird die dynamische Codeauswertung verwendet.

Benutzerdefinierte Metadaten mit user_meta

Mit dem optionalen Parameter user_meta fügen Sie jeder von einem Step ausgegebenen Datei JSON-Werte hinzu. Nachgelagerte Steps lesen sie als ${file.user_meta.key}. Werte können verschachtelte Objekte und Arrays enthalten. Sie verändern weder den Dateiinhalt noch vertrauenswürdige Eigenschaften wie file.id oder file.meta.

Bei verarbeitenden Steps werden die Werte nach der Ausführung des Robots für jede ausgegebene Datei separat ausgewertet. Innerhalb von user_meta bezeichnet ${file.*} die erste Eingabedatei und ${result.*} die Ausgabedatei. Beispielsweise kann /file/hash den Wert ${result.meta.hash} speichern. Es stehen nur bereits vorhandene Ausgabeeigenschaften zur Verfügung: Die Auswertung erfolgt vor der anschließenden Metadatenextraktion und temporären Speicherung. In gewöhnlichen Robot-Parametern ist ${result.*} nicht verfügbar.

Bei :original (/upload/handle) werden die Werte für jeden Upload separat vor der Metadatenextraktion ausgewertet. Verlassen Sie sich dort nicht auf extrahierte Hashes oder Abmessungen. Um den Hash der hochgeladenen Datei zu bewahren, weisen Sie ${file.md5hash} im ersten verarbeitenden Step zu, wie unten gezeigt.

Die Vererbung hängt vom Robot ab. /image/resize übernimmt Metadaten der ersten Eingabedatei; Zuordnungen mehrerer Eingaben werden nicht zusammengeführt. Robots wie /html/convert, die neue Ausgabedateien erstellen, erben die Zuordnung möglicherweise nicht. Weisen Sie benötigte Schlüssel in diesen Steps ausdrücklich mit ${file.user_meta.key} zu. Die Werte des aktuellen Steps ersetzen übereinstimmende Schlüssel auf der obersten Ebene der Ausgabedatei; verschachtelte Objekte werden ersetzt, nicht rekursiv zusammengeführt.

Den Hash des hochgeladenen Bildes bewahren

Konfigurieren Sie die benannten S3-Template-Zugangsdaten und übergeben Sie das Anfragefeld customer, bevor Sie dieses Beispiel verwenden. Der Resize-Step speichert den Hash des Eingabebildes; der Export-Step liest diesen gespeicherten Wert statt des Hashes der skalierten Datei.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "user_meta": {
        "stage": "uploaded"
      }
    },
    "resized": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 640,
      "height": 640,
      "resize_strategy": "fit",
      "result": true,
      "user_meta": {
        "source_md5": "${file.md5hash}",
        "stage": "resized",
        "source": {
          "name": "${file.name}"
        },
        "tags": [
          "profile",
          "${fields.customer}"
        ]
      }
    },
    "exported": {
      "use": "resized",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS_NAME",
      "path": "${file.user_meta.source_md5}/${unique_prefix}/${file.url_name}"
    }
  }
}

Das Ergebnis resized enthält user_meta mit source_md5, dem aktualisierten stage, einem verschachtelten Objekt source und einem Array tags. ${unique_prefix} hält Exportpfade auch bei identischen Uploads eindeutig. Dateiobjekte geben diese Metadaten in der Assembly-Status-Antwort aus. Speichern Sie darin keine Geheimnisse.

Den passenden Metadatenbereich wählen

fields enthält Anfragewerte auf Assembly-Ebene. meta enthält erkannte Dateimetadaten. user_meta enthält benutzerdefinierte Werte je Datei, einschließlich zusätzlicher Metadaten aus tus-Uploads. Ein fehlender Wert oder null ergibt über eine einfache Assembly Variable eine leere Zeichenfolge; eine eigenständige numerische oder boolesche Variable behält ihren Typ.

Beispiel für Assembly Variables

Angenommen, Ihnen gefällt der Speicherort Ihrer Dateien nicht. Standardmäßig achtet Transloadit sorgfältig darauf, nichts zu überschreiben. Alle Export-Robots besitzen einen Parameter path mit dem Standardwert "${unique_prefix}/${file.url_name}". Daraus entstehen Speicherorte wie: "f2/d3eeeb67479f11f8b091b04f6181ad/my-file-name.png".

Wir könnten den Parameterwert beispielsweise in "${previous_step.name}/${file.id}.${file.ext}" ändern. Die Pfade würden dann wie folgt aussehen: "video-step-name/a8d3eeeb67479f11f8b091b04f6181ad.png".

Nicht alle Assembly Variables sind gleich. Einige sind eindeutiger und daher besser als alleinige Grundlage für den Speicherort geeignet. Hier einige Beispiele, geordnet von weniger bis stärker eindeutig:

  • ${file.ext} ist bei vielen Dateien identisch
  • ${file.url_name} birgt insbesondere über verschiedene nutzende Personen und Zeiträume hinweg eine hohe Konfliktwahrscheinlichkeit, beispielsweise: avatar.jpg
  • ${previous_step.name} ist bei allen Dateien identisch, die Ergebnisse von demselben Step sind
  • ${assembly.id} ist für alle Dateien innerhalb einer einzelnen Assembly identisch
  • ${file.id} und ${unique_prefix} sind für jede Datei eindeutig

Falls Assembly Variables für Ihren Anwendungsfall nicht genügend Flexibilität bieten, steht Ihnen außerdem die dynamische Codeausführung mit dem Robot /script/run zur Verfügung. Damit können Sie JavaScript aus Ihren Assembly Instructions auswerten lassen.