Assembly Instructions
Assembly Instructionsを理解するには、次の例を見ると分かりやすいです。
{
"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}"
}
}
}
この例には、4つのStepがあります。:original、imported_watermark、resized、exported です。Stepには任意の名前を付けられますが、:original だけは例外です。これはアップロードしたファイルを指すため、🤖/upload/handle Robot を使う必要があります。
:original と imported_watermark の両方の
Stepが、resized の
Stepの入力として、use
パラメーターを介して使われている点に注目してください。ここでは、「as」構文で Step のバンドル を使い、複数のファイルを
resized のStepに同時に渡しています。1つはベース画像として、もう 1つはベース画像の上に重ねる透かしとして渡します。「as」構文でできることは Robot ごとに異なります。この構文は非常に強力です。
exported の Step は、他の
Stepの大半を入力として使い、Step のバンドルを使わずに 1つずつ S3 に保存するだけです。使用している変数 ${file.id} と ${file.url_name} は、すべてのStepで利用でき、各ファイルに一意のファイル名を作るのに使えます。
これにより、アップロードしたファイルを処理し、透かしを追加し、元の画像と、サイズ変更して透かしを付けた派生画像の両方を S3 にエクスポートできます。
すべてのStepに入力が必要なわけではありません。たとえば imported_watermark の
Stepは、ファイルをダウンロードして最初の入力を自分で用意するため、ここでは use を省いています。入力ファイルを必要としないRobotの例には、Web サイトのスクリーンショットを取得して最初のファイルを生成できる
🤖/html/convert Robot や、別の
Stepではなくアプリの訪問者からファイルを受け取る
🤖/upload/handle Robot があります。
たった 1つの変更で、このアプリを本当に動的にできます。imported_watermark のStepにある固定の URL を、アプリのフィールドから受け取る動的な URL に置き換える場面を想像してみてください。必要なのは、Templateで
"url" パラメーターを "${fields.watermark_url}" に変更し、その入力フィールドを HTML の Web フォーム(またはリクエストの追加の POST フィールド)で渡すことだけです。これで透かし処理を本当に動的にできます。
Step パラメーター
ご覧のとおり、各Stepは、いくつかのプロパティ、つまりパラメーターを持つオブジェクトとして定義します。その大半は実際には
Robot Parameterで、たとえばサイズ変更後の画像の
width を指定します。これらについては、それぞれの
Robot ドキュメントで説明しています。一方で、Assemblyエンジン自体に指示を出し、どのRobotを呼び出してどう接続するかを定義するパラメーターも 5つあります。
usestring | Array<string> | Array<object> | object入力として使用する Step を指定します。
- Step には任意の名前を付けられます。ただし、
":original"は Transloadit が処理するユーザーアップロード用に予約されています。 - 配列を使用して、複数の Step を入力として指定できます。
{ "use": [ ":original", "encoded", "resized" ] } - 入力 Step に
asでタグを付けて、意味上の用途を Robot に伝えることもできます。{ "use": [ { "name": ":original", "as": "image" }, { "name": ":original", "as": "mask" } ] }
ヒントuseについては、通常ここまでの内容で十分ですが、高度な使用例 も参照できます。- Step には任意の名前を付けられます。ただし、
robot— 必須stringこの Step に渡されたファイルを処理する Robot を指定します。
すべての Robot を参照してください。各 Robot には固有のパラメーターがあります。たとえば、
widthは画像のリサイズ方法を制御します。Robot ごとのパラメーターの全一覧は、各 Robot のドキュメントで確認できます。resultboolean(デフォルト:false)この Step の結果を Assembly Status JSON に含めるかどうか
force_acceptboolean(デフォルト:false)通常は無視するファイルタイプを Robot に強制的に受け入れさせます。
デフォルトでは、Robot は認識できないファイルを無視します。たとえば、🤖/video/encodeは入力画像を無視します。
force_acceptパラメーターをtrueに設定すると、Robot に渡されたすべてのファイルを強制的に受け入れさせることができます。通常、この設定はエラーにつながるため、デバッグやエッジケースへの対処にのみ使用してください。ignore_errorsboolean | Array<meta | execute>(デフォルト:[])処理の特定のフェーズでエラーを無視します。
このパラメーターを
["meta"]に設定すると、Robot はメタデータ抽出中のエラーを無視します。このパラメーターを
["execute"]に設定すると、Robot はメイン実行フェーズ中のエラーを無視します。このパラメーターを
trueに設定すると、["meta", "execute"]と同じ動作になり、両方のフェーズでエラーを無視します。
実践的なガイダンスや値の組み合わせ(インポート固有の挙動を含みます)については、ignore_errors パラメーターを参照してください。
実行順序
Assemblyを高速化するため、Stepは入力元の Stepがファイルを出力するとすぐに実行されます。つまり、多くの処理が並列に進みます。たとえば、アップロードした動画をエンコードし、そこからサムネイルも抽出したいとします。
{
"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"
}
}
}
encoded と thumbed の
Stepは、最初のファイルのアップロードが完了するとすぐに並列で実行されます。exported の
Stepは、encoded と
thumbed から来るファイルごとに実行されます。サムネイルは後ろで定義されていますが、エンコードされた動画より先に S3 バケットへ到達する可能性が高いです。そのため、Stepの記述順序は実際にはそれほど重要ではありません。use パラメーターが各
Stepの入力を定義し、それによって
Stepをどう連結するかが最終的に決まります。
フィルタリングで Step を条件付きで実行する
🤖/file/filterを使うと、ファイルのプロパティに基づいて Stepを実行できます。これにより、動画と音声の両方のアップロードに対応する、小さすぎるファイルを拒否する、透明領域がある画像にだけエフェクトを適用するといったAssembly Instructionsを作成できます。こうしたことや他の例についても、Robotのドキュメントで説明しています。
Assembly Variable
${file.id}、${assembly.id}、${fields.*} などの Assembly Variable については、専用の
Assembly Variableページを参照してください。