Templates

Ein Template ist ein Rezept, das definiert, wie eingehende Dateien verarbeitet werden.

Sie können uns Ihre Assembly Instructions direkt mit jeder Anfrage senden oder sie in einem Template speichern und in Ihren Anfragen über die template_id darauf verweisen.

Builtin Templates

Transloadit bietet außerdem von uns gepflegte und versionierte Templates. Diese Builtin Templates eignen sich als stabile, sofort einsatzbereite Ausgangspunkte für gängige Transformationen.

Unter Builtin Templates erfahren Sie, welche Builtins verfügbar sind und wie Sie sie über die API auflisten.

Wenn Sie Instructions direkt senden, können Sie schnell Prototypen erstellen. Das Speichern in einem Template bietet jedoch einige Vorteile:

1. Sie müssen nicht bei jeder Anfrage zum Codieren vertrauliche Daten und Implementierungsdetails übertragen. Das ist besonders relevant, wenn Sie Browser integrieren.
2. In Kombination mit "allow_steps_override": false können Instructions nicht manipuliert werden.
3. In Kombination mit Assembly Notifications können Sie Assembly Replays aktivieren.
4. Wenn Sie Transloadit in eine App integriert haben, können Sie die Encoding-Einstellungen ohne Deployment ändern, ohne darauf zu warten, dass ein App Store eine neue Version veröffentlicht.

So erstellen Sie ein Template

1. Erstellen Sie ein Template in Ihrem Konto.
2. Geben Sie Ihrem Template einen Namen, damit Sie es später leicht erkennen können.
3. Geben Sie den JSON-Code der Assembly Instructions für Ihr Template an. Sie können Beispiele aus einer Liste auswählen, mit unserem Assistenten Instructions generieren, ein vorhandenes Template duplizieren oder neu beginnen.
4. Speichern Sie das Template.

Nachdem das Template gespeichert wurde, erscheint eine Seite mit dem von Ihnen erstellten Template. Oben auf der Seite wird die Template-ID angezeigt, z. B. 4b62ee4dbb38455d96fe13d972ec3211. Anschließend können Sie diese ID kopieren und in Ihrem Integrationscode als template_id einfügen oder weiter unten im Template Editor Beispiele aufrufen, die diese ID bereits enthalten.

Templates zur Laufzeit überschreiben

Man könnte annehmen, dass sich beide Optionen gegenseitig ausschließen. Sie können jedoch sowohl template_id als auch steps in den Parametern angeben und so das Template-Verhalten zur Laufzeit ändern. Tatsächlich wird jede andere Eigenschaft in params mit Ausnahme von allow_steps_override rekursiv über das per template_id geladene Template gelegt.

Sehen wir uns beispielsweise das folgende Template an. Es verarbeitet einen Upload, codiert ein Video für eine optimale Wiedergabe auf iPads und speichert das Ergebnis auf S3:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "ipad-high"
    },
    "exported": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS",
      "bucket": "main-bucket"
    }
  }
}

Wenn Sie eine Assembly erstellen, können Sie das Template-Verhalten zur Laufzeit anpassen, beispielsweise durch Hinzufügen einer steps-Eigenschaft:

{
  "template_id": "4b62ee4dbb38455d96fe13d972ec3211",
  "steps": {
    "exported": {
      "bucket": "another-bucket"
    }
  }
}

Transloadit führt diese Angaben anschließend zu den folgenden Assembly Instructions zusammen:

{
  "steps": {
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "ipad-high"
    },
    "exported": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS",
      "bucket": "another-bucket"
    }
  }
}

Wie Sie sehen, wurde der Wert bucket von "main-bucket" in "another-bucket" geändert. Dies kann in vertrauenswürdigen Umgebungen praktisch und leistungsstark sein.

In anderen Umgebungen empfiehlt es sich möglicherweise, das Überschreiben von Steps zu verhindern, damit ein Browser das Verhalten nicht ändern kann. Legen Sie dazu im gespeicherten Template allow_steps_override wie folgt auf false fest:

{
  "allow_steps_override": false,
  "steps": {
    // …
  },
}

Nun wird immer ausschließlich main-bucket verwendet, unabhängig davon, ob zusätzliche steps angegeben wurden.

Template-Optionen

Neben steps und allow_steps_override stehen weitere Optionen zur Steuerung des Verhaltens bei einer Assembly zur Verfügung.

Da sich die meisten davon auch ohne Templates festlegen lassen, sind sie in der API-Dokumentation zum Erstellen einer neuen Assembly beschrieben. Wenn Sie Transloadit jedoch in nicht vertrauenswürdige Umgebungen wie Browser integrieren, könnten Angreifer diese Optionen leicht ändern. Wenn Sie Template-Parameter in nicht vertrauenswürdigen Umgebungen dynamisch ändern möchten, sollten Sie daher Signature Authentication verwenden.