Assembly Instructions

Sehen wir uns dieses Beispiel an, um Assembly Instructions kennenzulernen:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "imported_watermark": {
      "robot": "/http/import",
      "url": "https://transloadit.com/assets/images/face.jpg"
    },
    "resized": {
      "robot": "/image/resize",
      "use": {
        "steps": [
          { "name": ":original", "as": "base" },
          { "name": "imported_watermark", "as": "watermark" }
        ]
      },
      "width": 400,
      "height": 400,
      "watermark_position": "center",
      "watermark_size": "30%"
    },
    "exported": {
      "robot": "/s3/store",
      "use": [":original", "resized"],
      "credentials": "my_cloud_storage_credentials",
      "path": "/my_images/${file.id}/${file.url_name}"
    }
  }
}

Das Beispiel zeigt vier Steps: :original, imported_watermark, resized und exported. Sie können Ihre Steps beliebig benennen. Die einzige Ausnahme ist :original: Dieser Step verweist auf hochgeladene Dateien und muss den Robot 🤖/upload/handle verwenden.

Beachten Sie, dass sowohl :original als auch imported_watermark als Steps über den Parameter use als Eingabe für den Step resized verwendet werden. Hier nutzen wir Step-Bündelung über die „as“-Syntax, um mehrere Dateien gleichzeitig an den Step resized zu übergeben: eine als Basisbild und eine als Wasserzeichen, das über das Basisbild gelegt wird. Verschiedene Robots bieten unterschiedliche Möglichkeiten für die „as“-Syntax, wodurch sich besonders leistungsstarke Workflows ergeben.

Der Step exported verwendet anschließend einfach die meisten anderen Steps als Eingabe und speichert sie einzeln auf S3 - ohne Step-Bündelung. Die verwendeten Variablen ${file.id} und ${file.url_name} stehen allen Steps zur Verfügung und ermöglichen eindeutige Dateinamen für jede Datei.

So können wir hochgeladene Dateien verarbeiten, mit einem Wasserzeichen versehen und sowohl das hochgeladene Bild als auch die skalierte Version mit Wasserzeichen nach S3 exportieren.

Nicht alle Steps benötigen Eingaben. Unser Step imported_watermark stellt beispielsweise die erste Eingabe bereit, indem er sie herunterlädt. Daher lassen wir hier use weg. Weitere Beispiele für Robots, die keine Eingabedateien benötigen, sind 🤖/html/convert, der einen Screenshot einer Website aufnehmen und so die erste Datei erstellen kann, sowie 🤖/upload/handle, der seine Dateien von den Besuchern Ihrer App statt von einem anderen Step erhält.

Mit einer einfachen Änderung könnten wir diese App vollständig dynamisch gestalten. Ersetzen Sie dazu die statische URL im Step imported_watermark durch eine dynamische URL aus einem Feld Ihrer App. Dazu müssen wir lediglich den Parameter "url" in unserem Template in "${fields.watermark_url}" ändern und dieses Eingabefeld anschließend in unserem HTML-Webformular oder über ein zusätzliches POST-Feld in unserer Anfrage bereitstellen. So wird das Wasserzeichen vollständig dynamisch.

Step-Parameter

Wie Sie sehen, wird jeder Step als Objekt mit einigen Eigenschaften oder Parametern definiert. Die meisten davon sind tatsächlich Robot Parameters. Sie geben beispielsweise die width eines Bildes nach der Größenänderung vor. Alle sind in der jeweiligen Robot-Dokumentation beschrieben. Es gibt jedoch auch 5 Parameter, die direkt die Engine der Assembly steuern. Sie legen fest, welche Robots aufgerufen und wie sie miteinander verbunden werden:

• use

  string | Array<string> | Array<object> | object

  Gibt an, welche Steps als Eingabe verwendet werden sollen.

  • Sie können beliebige Namen für Steps wählen, außer ":original" (reserviert für von Transloadit verarbeitete Benutzer-Uploads)
  • Sie können mehrere Steps mithilfe von Arrays als Eingabe angeben:

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • Sie können Eingabe-Steps außerdem mit as kennzeichnen, um Robots die semantische Funktion zu übermitteln:

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Tipp

  Das ist wahrscheinlich alles, was Sie über use wissen müssen. Sie können sich jedoch auch die erweiterten Anwendungsfälle ansehen.

• robot — erforderlich

  string

  Gibt an, welcher Robot die an diesen Step übergebenen Dateien verarbeiten soll.

  Unter alle Robots finden Sie die verfügbaren Robots mit ihren jeweiligen Parametern, beispielsweise width zum Steuern der Größenänderung eines Bildes. Die vollständige Parameterliste für jeden Robot finden Sie in der Robot-Dokumentation.

• result

  boolean(Standard: false)

  Ob die Ergebnisse dieses Steps im Assembly Status JSON enthalten sein sollen

• force_accept

  boolean(Standard: false)

  Erzwingt, dass ein Robot einen Dateityp akzeptiert, den er sonst ignorieren würde.

  Standardmäßig ignorieren Robots Dateien, deren Typ sie nicht kennen. 🤖/video/encode ignoriert beispielsweise problemlos Eingabebilder.

  Wenn Sie den Parameter force_accept auf true setzen, können Sie erzwingen, dass Robots alle übergebenen Dateien akzeptieren. Dies führt in der Regel zu Fehlern und sollte nur zur Fehlersuche oder zur Behandlung von Grenzfällen verwendet werden.

• ignore_errors

  boolean | Array<meta | execute>(Standard: [])

  Fehler in bestimmten Verarbeitungsphasen ignorieren.

  Wenn Sie hierfür ["meta"] festlegen, ignoriert der Robot Fehler bei der Metadatenextraktion.

  Wenn Sie hierfür ["execute"] festlegen, ignoriert der Robot Fehler während der Hauptausführungsphase.

  Wenn Sie hierfür true festlegen, entspricht dies ["meta", "execute"] und Fehler in beiden Phasen werden ignoriert.

Praktische Hinweise und mögliche Wertekombinationen einschließlich importspezifischen Verhaltens finden Sie unter Der Parameter ignore_errors.

Ausführungsreihenfolge

Um Assemblies zu beschleunigen, werden Steps ausgeführt, sobald die als Eingabe dienenden Steps Dateien ausgeben. Das bedeutet, dass viele Vorgänge parallel verarbeitet werden. Angenommen, Sie möchten beispielsweise ein hochgeladenes Video codieren und zugleich Thumbnails daraus extrahieren:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/1080p"
    },
    "thumbed": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 4
    },
    "exported": {
      "use": ["encoded", "thumbed"],
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS"
    }
  }
}

Die beiden Steps encoded und thumbed werden parallel ausgeführt, sobald der erste Datei-Upload abgeschlossen ist. Der Step exported wird für jede Datei ausgelöst, die von encoded und thumbed stammt. Wahrscheinlich erreichen die Thumbnails Ihren S3-Bucket vor dem für das iPad optimierten Video, obwohl die Thumbnails später definiert wurden. Daher spielt die Reihenfolge der Steps keine wesentliche Rolle. Der Parameter use definiert die Eingabe für jeden Step und bestimmt damit letztlich, wie unsere Steps miteinander verkettet werden.

Filtern, um Steps bedingt auszuführen

Mit 🤖/file/filter können Sie Steps anhand der Eigenschaften einer Datei ausführen. So können Sie Assembly Instructions erstellen, die sowohl Video- als auch Audio-Uploads verarbeiten, zu kleine Dateien ablehnen oder einen Effekt nur auf Bilder mit transparenten Bereichen anwenden. Diese und weitere Möglichkeiten werden auch in der Dokumentation zu diesem Robot beschrieben.

Assembly Variables

Informationen zu Assembly Variables wie ${file.id}, ${assembly.id}, ${fields.*} und weiteren finden Sie auf der eigenen Seite Assembly Variables.