Template とは何ですか?

Template は、Transloadit の Assembly Instructions を Workspace 内に安全に保存し、API リクエストでは template_id を通じて参照されます。これにより、クライアントはその Assembly Instructions 全体を送信せずに、事前定義された処理ワークフローを呼び出せます。

Template の仕組み

Transloadit の Template は、Workspace で管理するワークフロー定義です。その JSON には、名前付きの Assembly Step、各パラメーター、先行する Step の出力を後続の Step に渡す流れを記述します。保存済みの定義を参照すれば、作成リクエストごとに処理設定全体を送信する必要はありません。ただし、ワークフローが機密になるわけではありません。Assembly Status から template と merged_params が公開される場合があります。リクエスト時に params で指定したプロパティは、allow_steps_override 自体を除き、Step の上書きポリシーに従って、読み込んだ Template に再帰的に上書きマージされます。このマージにより、実行時に設定を変えることもできます。Template はアプリケーションのリクエストと Assembly の実行の間に位置するため、その変更管理も連携仕様の一部です。

要点

  1. Step 名は Assembly Instructions 内の参照に使われるため、Step 名を変更すると、個々の操作がすべて構文上は有効でも、後続の use の関係が壊れる場合があります。
  2. template_id は保存済みの処理設定を選択しますが、それ自体では API リクエストを認証しません。アカウント認証と、リクエスト署名が必要な場合の要件は、それぞれ別の制御です。
  3. 保存済みの Template で allow_steps_override を false に設定すると、Step も指定するリクエストを拒否できます。他のリクエストパラメーターでは、引き続き保存済みの値を上書きできます。Auth Key を使うリクエストには Signature Authentication を必須とし、信頼できるバックエンドで承認済みのパラメーターだけに署名してください。有効な Bearer トークンにはこの要件が適用されず、引き続きそのスコープとオーディエンスの制限が適用されます。Signature の対象はシリアライズされた params であり、別個のアップロードフォームフィールドではありません。これらの未署名フィールドは ${fields.*} に格納され、同名の署名済み fields の値を上書きするため、これらの制御だけでは動的入力を保護できません。呼び出し元に選択を許可すべきでない設定を、これらのフィールドから導出しないでください。
  4. Workspace で作成した Template は、バージョンを固定できません。後方互換性のない変更を安全に行うには、独自の template_id を持つ新しい Template を作成し、呼び出し元を移行してください。Transloadit がバージョン管理するのは、Transloadit の Builtin Template のみです。

Template が重要になる場面

Template を使うと、ワークフローの変更を一元管理でき、作成リクエストごとに Assembly Instructions 全体を送信する必要がなくなります。Step の上書きを防ぐには allow_steps_override を false に設定し、Auth Key を使うリクエストには、信頼できる署名処理による Signature Authentication を必須にしてください。これらの制御は未署名のアップロードフィールドを制限せず、Bearer トークンのスコープ制限の代わりにもならないため、動的入力は別途確認してください。共有 Template の更新はすべての呼び出し元に影響する可能性があるため、互換性のない変更には新しい Template が必要になる場合があります。

メディアの知識を実用的なパイプラインに

単一の宣言的 API で、アップロード、処理、AI、ストレージ、配信を連携できます。エンコードスタックの管理、スケーリング、形式の変化への対応はお任せください。

Transloadit を無料で試す