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} — tus-Uploads, mit denen Sie Dateien zu Transloadit hochladen, können Metadatenwerte enthalten. Alle zusätzlich gesendeten Werte werden in user_meta gespeichert. Dabei handelt es sich um benutzerdefinierte Metadaten, die Sie selbst bereitstellen, nicht um den von Transloadit erkannten Dateityp oder MIME-Typ.

  • ${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.

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.