Assembly とは?

Transloadit の Assembly は、アップロードまたはインポートされたファイル、あるいはワークフロー自体が生成したファイルに対する Assembly Instructions の 1 回の実行です。各実行には、後続の API リクエストでその実行を識別するための一意の assembly_id があります。

Assembly の仕組み

Assembly は、リクエストが Assembly Instructions と入力ソースを組み合わせたときに作成される、実行時のワークフローです。入力ソースには、アップロードされたファイル、インポート Step が取得したファイル、ウェブサイトのスクリーンショットやテキストプロンプトから生成した画像など、Robot 自体が作成したファイルがあります。処理設定は steps としてインラインで渡すか、template_id を通じて保存済みの Template を参照して渡します。Template は設定を保存し、Assembly はその設定の個別の実行に当たります。Step は、依存先の Step がファイルを出力するとすぐに開始されるため、一つのソースファイルを、並列実行される複数の分岐に渡せます。Transloadit は、一つの Assembly Status ドキュメントを通じて実行状況を報告します。このドキュメントは Assembly の作成時に返され、ステータス URL で提供されるほか、notify_url が設定されていれば、その送信先にも送られます。ドキュメントは Assembly のアップロード中や実行中に変化します。実行が終了状態に達すると、最終状態を示す ok、またはエラーコードを示す error が含まれます。

要点

  1. 作成リクエストへの HTTP 成功レスポンスは、Assembly が受け付けられたことを意味し、処理の成功を意味するものではありません。ok が ASSEMBLY_UPLOADING、ASSEMBLY_EXECUTING、または ASSEMBLY_REPLAYING の間は、Assembly はまだ実行中です。成功を意味するのは ASSEMBLY_COMPLETED だけです。ASSEMBLY_CANCELED と REQUEST_ABORTED も、成功ではないものの、ok に現れます。また、ステータスリクエストが HTTP 200 を返しても、本文に error が含まれる場合があります。そのため、HTTP ステータスではなく、本文に基づいて分岐してください。
  2. assembly_id はアクセス権を与える情報として機能します。これを知っていれば、追加の認証なしに、送信されたフィールドや結果を含む Assembly Status を取得できます。ID とステータス URL は、公開ページや、信頼できない相手と共有するものに含めないでください。quiet オプションは作成時のレスポンスを短くするだけで、その後にステータスを読み取れる相手を制限するものではありません。
  3. Assembly の作成は冪等ではありません。タイムアウト後などに作成リクエストを再試行すると、独自の assembly_id を持つ二つ目の Assembly が開始されることがあり、署名用の nonce を追加しても防げません。アプリケーション側で再試行の重複を排除してください。
  4. 結果ファイルはアップロード順ではなく、生成した Step の名前ごとにまとめられます。一つのアップロードから複数の結果が生成されることもあるため、original_id を使ってアップロードと対応付けてください。ファイルの保存だけを行う Step はエントリーを追加せず、エラー後の結果は部分的な場合があります。Transloadit の一時ストレージにある結果 URL には有効期限があるため、ファイルを保持する必要がある場合は、エクスポート Step を追加してください。

Assembly が重要になる場面

ワークフローでステータスのポーリング、結果の収集、受信した Notification と開始元リクエストの照合が必要な場合は、assembly_id をサーバーに保存してください。ID だけで Assembly Status を読み取れるため、機密情報として扱ってください。作成リクエストへのレスポンスで確認できるのは、Assembly が受け付けられたことだけです。そのため、ステータス URL をポーリングするか、notify_url を設定するか、アプリケーションで結果を把握する方法を運用開始前に決めてください。

出典

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

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

Transloadit を無料で試す