use パラメーターの高度な設定
use パラメーターの高度なオプションで、入力の処理方法を細かく制御できます。入力を組み合わせたり、特定の順序で処理したりする必要がある
Stepなど、複雑なケースで特に役立ちます。
Step のバンドル
一部のRobotは、複数の
Stepの結果をまとめて、1 回の呼び出しで処理できます。たとえば、🤖/file/compressは通常、渡されたファイルごとにアーカイブを作成します。ただし、bundle_steps を true に設定すると、渡したすべてのStepの結果ファイルを含む
1 つのアーカイブを作成します。
バンドルを有効にするには、use パラメーターに次のようなオブジェクトを指定します。
"use": {
"steps": [
":original",
"encoded",
"resized"
],
"bundle_steps": true
}
bundle_steps パラメーターは、🤖/video/adaptiveに必須です。指定しないと、視聴画質ごとにマスタープレイリストファイルが生成されます。
元のファイルごとのグループ化
group_by_original パラメーターは、出力ファイルを元の入力ファイルごとにまとめます。出力をその生成元の入力ファイルと確実にグループ化したいワークフローで不可欠です。たとえば、🤖/file/compress
Robotを使う場合が該当します。この場合、元のアップロードファイルすべてをまとめたアーカイブや、結果ファイルごとのアーカイブではなく、アップロードまたはインポートしたファイルごとに個別のアーカイブを作成したいことがあります。
例:
"compress": {
"use": {
"steps": ["thumbnails"],
"bundle_steps": true,
"group_by_original": true
},
"robot": "/file/compress"
}
この設定では、compress Stepが
thumbnails Stepの出力を受け取り、元のファイルごとにまとめて圧縮します。
フィールド
fields 設定を使うと、フィールド名に基づいて特定のファイルを絞り込み、選択できます。この配列を指定すると、指定したいずれかのフィールド名で送信されたファイルに対してのみ、該当するStepが実行されます。
フィールド名は、HTML フォームのファイル入力タグの
name 属性で定義した名前と一致する必要があります。バックエンド SDK を使う場合は、たとえば $transloadit->addFile('myFieldName1', './chameleon.jpg') の
myFieldName1 に相当します。
例:
"use": {
"steps": [":original"],
"fields": ["myFieldName1"]
}
このパラメーターのデフォルト値は true で、すべてのフィールドを受け入れます。
as の使用
Robotによっては、複数の入力を受け取ります。たとえば、🤖/video/mergeは、音声と画像からスライドショーを作成できます。各Stepをどのファイルタイプとして扱うか指定すると、Stepごとに適切な入力に割り当てられます。
"use": {
"steps": [
{ "name": "audio_encoded", "as": "audio" },
{ "name": "images_resized", "as": "image" }
]
}
Step の順序
処理順序が重要な場合もあります。たとえば、当社の連結用
Robotでは、メディアを連結する順序を厳密に指定したいことがあります。その場合は、ファイルタイプの末尾に 1 から始まるインデックスを追加できます。必要に応じて、マルチパートのフィールド名による絞り込みもできます。次の例では、すべてのファイルのソースは同じ(エンドユーザーによるアップロード)ですが、<input> の名前が異なります。
"use": {
"steps": [
{ "name": ":original", "fields": "myFirstVideo", "as": "video_1" },
{ "name": ":original", "fields": "mySecondVideo", "as": "video_2" },
{ "name": ":original", "fields": "myThirdVideo", "as": "video_3" }
]
}
ファイルの割り当て先が明確でない場合は、Assembly Variableで明示できます。たとえば、🤖/image/resizeにテキストファイルを渡して、テキストを画像に焼き込みたい場合があります。画像に複数の透かしを焼き込む場合、使用するテキストファイルはどのように指定すればよいでしょうか。${use.text_1} で、最初に渡されたテキストファイルを指定できます。
例:
"watermarked": {
"robot": "/image/resize",
"use": {
"steps": [
{ "name": "resized", "as": "base" },
{ "name": "transcribed", "as": "text" }
]
},
"text": [
{
"text": "Hi there",
"valign": "top",
"align": "left"
},
{
"text": "From the 'transcribed' Step: ${use.text_1}",
"valign": "bottom",
"align": "right",
"x_offset": 16,
"y_offset": -10
}
]
}
Assembly Step による透かしの指定
use パラメーターを使うと、ベース画像ファイルと透かし画像の両方を
Assembly Stepに渡すこともできます。両方をアップロードに含めたり、ほかの
Assembly Stepの結果を
🤖/image/resizeを使うStepの入力にしたりできます。
これを行うには、as 構文を使うだけです。
"my_image_step": {
"robot": "/image/resize",
"use": {
"steps": [
{ "name": ":original", "as": "base" },
{ "name": "watermark_step", "as": "watermark" }
]
}
}
ここでは、watermark_step ステップの出力を透かしとして使用し、ベース画像はアップロードされたファイルから取得します。
複数のファイル入力フィールドを使う場合は、ベース画像と透かしをそれぞれどのフィールドから取得するかを
Transloadit に指定できます。the_image と
the_watermark という名前のファイル入力フィールドがあるとします。次のAssembly Instructionsでは、fields 条件を使ってこれを実現します。
"my_image_step": {
"robot": "/image/resize",
"use": {
"steps": [
{ "name": ":original", "fields": "the_image", "as": "base" },
{ "name": ":original", "fields": "the_watermark", "as": "watermark" }
]
}
}
Robotの watermark_url パラメーターも引き続き機能する点にご注意ください。