Assembly Instructions とは?
Transloadit の Assembly Instructions は、ファイル処理ワークフロー内の名前付き Steps を定義します。各 Step は Robot とそのパラメーターを選択します。use パラメーターは、アップロード、インポート、または生成されたファイルが Steps 間をどのように流れるかを決定します。
Assembly Instructions の仕組み
処理設定は、名前付き Step の設定と入力の関係で表現される、有向非巡回処理グラフを構成します。各 Step で Robot とパラメーターを選択し、use で入力となるアップロードや先行する処理結果を指定します。ファイルをインポートまたは生成する Step は、先行する Step に依存しなければ use を省略できます。それ以外の Step で use を省略すると、直前の Step の出力に暗黙的に接続されます。最初に宣言した Step のデフォルトの入力は :original です。Step の順序でグラフを決めたくない場合は、use を明示的に宣言してください。予約済みの Step 名 :original は、アップロードされたファイルを指します。この名前で宣言した Step で実行できるのは Robot /upload/handle だけで、他の Step ではこの Robot を実行できません。use の値では、:original を Step として宣言せずに参照できます。処理設定ドキュメントは、グラフの一回の実行である Assembly や、処理設定を再利用のために保存する Template とは別のものです。メディア処理の開始前に、Transloadit は各 Step が既存の Robot を指定する正しい形式のオブジェクトであること、宣言された use の参照がすべて解決できること、グラフに循環がないことを検証します。
要点
- Step 名はグラフの識別子です。
useが存在しない Step を指定している場合、Transloadit は処理の開始前に ASSEMBLY_STEP_UNKNOWN_USE(HTTP 400)で Assembly を拒否します。 - ある Step の結果を後続の複数の Step に渡せるため、派生ファイルごとにアップロードやインポートを行う必要はありません。これらの Step は、入力元の Step がファイルを出力し次第、並列で実行されます。そのため、
useの値を明示している場合、Step の宣言順序は結果の生成順序やエクスポート順序を決めません。宣言順序が影響するのは、Step がuseを省略し、直前の Step に暗黙的に接続される場合だけです。 - Template を使うと、再利用するワークフローのロジックをクライアントのリクエストから分離できます。デフォルトでは、クライアントは Step を上書きできます。Template で
allow_steps_overrideを false に設定すると、それでも Step を指定するリクエストは TEMPLATE_DENIES_STEPS_OVERRIDE(HTTP 400)で拒否されます。この設定の対象は Step だけで、他のリクエストパラメーターは引き続き Template に上書きマージされます。信頼できない呼び出し元がこれらを変更できないようにするには、Signature Authentication を必須にし、信頼できるバックエンドで承認したパラメーターだけに署名してください。必須化には Workspace の設定、または Template のrequire_signature_authを使用します。この要件は Auth Key で認証するリクエストに適用され、有効な Bearer トークンはこの要件を回避します。署名の対象は、シリアライズされたparamsだけです。それと一緒に送信されるアップロードフォームのフィールドには署名がなく、${fields.*}に入り、署名付きのfieldsキー内の同名の値より優先されます。そのため、ロックした Template でも、${fields.*}からストレージパスなどの設定を組み立てる場合は、呼び出し元がその値を選択できます。 - 何も出力しない Step が、必ずしも失敗したとは限りません。デフォルトでは、Robot は扱わないファイル形式を無視します(ドキュメントでは
/video/encodeが画像を無視する例を挙げています)。そのため、分岐によっては、そのようなファイルに対して何も出力しないだけの場合があります。形式が混在するアップロードを意図どおりに振り分けるには、/file/filterを使用してください。ドキュメントでは、force_acceptの用途をデバッグと特殊なケースに限定しています。
Assembly Instructions が重要になる場面
呼び出し元にサーバー管理のワークフローを再利用させる場合は、処理設定を Template に保存してください。呼び出し元による Step の変更を禁止するには、allow_steps_override を false に設定します。他のリクエストパラメーターの変更も禁止するには、Auth Key を使うリクエストで Signature Authentication を必須にしてください。どちらの制御もアップロードフォームのフィールドは対象にしません。そのため、呼び出し元に選択させてはいけない設定を ${fields.*} から導出しないでください。処理設定を生成したり Step の名前を変更したりする場合は、Assembly が検証を通過するように、すべての use の値が、宣言済みの Step 名または :original を参照していることを確認してください。
Assembly Instructions に対する Transloadit の支援
Transloadit は、Assembly のワークフローとして Assembly Instructions を検証し、実行します。名前付きの各 Step は一つの Robot を呼び出し、ファイルのアップロード、インポート、処理、分析、保存、配信のいずれかを行います。use パラメーターは、Step 間で結果を振り分けます。Template は処理設定を再利用のために保存し、Assembly はその一回の実行に当たります。Assembly Status と Notification は、その結果を報告します。
出典
- Transloadit ドキュメント:Assembly Instructions(Step のパラメーター、実行順序)
- Transloadit ドキュメント:use パラメーターの高度な使い方
- Transloadit ドキュメント:Template(実行時の Template の上書き)
- Transloadit API:レスポンスコード(Step と Template の検証エラー)
- Transloadit Robot:/upload/handle(:original Step の制約)
- Transloadit API:新しい Template の作成(allow_steps_override、require_signature_auth)
- Transloadit API:認証(Signature Authentication、Bearer トークン)
- Transloadit Robot:/file/filter(条件付き Step)
- Transloadit ドキュメント:Assembly Variable(フォームフィールドと fields キー)
- Transloadit FAQ:画像が実際に正しいユーザーから送られたことを確認するには?(署名の対象範囲)