Assembly Variable
Transloadit では、Assembly で変数を使えるため、より強力なワークフローを構築できます。たとえば、width に基づいてファイルを絞り込んだり、type に基づいて保存先を変えたりできます。そのほかにもさまざまな用途があります。Assembly Variable で使えるプレースホルダー変数の一覧を以下にまとめました。これらは任意の Robot の任意のパラメーター値で使用できます。
ファイルが持っていないプロパティーに対する条件は無視されます。たとえば、画像には
${file.meta.bitrate} がありません。また、${file.width} は無視されるため、代わりに ${file.meta.width} を使用してください。
-
${assembly.id}— 現在のアップロードを表す Assembly の ID です。ハイフンなしの UUIDv4 です。 -
${assembly.region}— Assembly を処理している AWS リージョンです。同じリージョンのバケットからファイルをインポートすることで、データ転送コストとレイテンシーを抑えられます。 -
${assembly.parent_id}— 親 Assembly をリプレイしているときの、親 Assembly の ID です。 -
${unique_prefix}— ファイル名の衝突を避けるための、一意な 33 文字のプレフィックスです。例:"f2/d3eeeb67479f11f8b091b04f6181ad"。このプレフィックスには
/が含まれる点に注意してください。たとえば、${unique_prefix}をpathパラメーターで使う 🤖/s3/store の設定では、S3 バケット内にサブディレクトリーが作成されます。これが望ましい場合もあれば、望ましくない場合もあります。スラッシュを含まない一意なプレフィックスが必要な場合は、${file.id}を使用してください。 -
${unique_original_prefix}—${unique_prefix}と似ていますが、同じアップロードファイル(元ファイル)から得られた 2 つの異なるエンコード結果では、ここに入るプレフィックス値は同じになります。 -
${previous_step.name}— 現在のファイルを生成した直前の Step 名です。 -
${file.id}— 処理中のファイルの ID です。ハイフンなしの UUIDv4 です。 -
${file.original_id}— あるファイルの派生元となる元ファイルの ID です。たとえば、インポート Robot でファイルを取り込み、その後何らかのエンコードを行うと、エンコード結果のファイルの${file.original_id}は、インポートしたファイルの${file.id}と一致します。 -
${file.original_name}— あるファイルの派生元となる元ファイル名です(拡張子を含みます)。たとえば、インポート Robot でファイルを取り込み、その後何らかのエンコードを行うと、エンコード結果のファイルの${file.original_name}は、インポートしたファイルの${file.name}と一致します。 -
${file.original_basename}— あるファイルの派生元となる元ファイルのベース名です。たとえば、インポート Robot でファイルを取り込み、その後何らかのエンコードを行うと、エンコード結果のファイルの${file.original_basename}は、インポートしたファイルの${file.basename}と一致します。 -
${file.original_path}— あるファイルの派生元となる元ファイルのインポートパスです。当社のすべてのインポート Robot は、それに応じて${file.original_path}を設定します。たとえば、🤖/s3/import を使って Amazon S3 からファイルをインポートすると、インポートされたファイルと、そこから派生したすべてのファイルには、S3 上のファイルパスからファイル名を除いた値と等しい
file.original_pathが設定されます。したがって、S3 パスが"path/to/file.txt"の場合、file.original_pathは"/path/to/"になります。パスが"/a.txt"の場合、${file.original_path}は"/"になります。file.original_pathには、エクスポート Step のpathパラメーターで安全に使えるよう、常に十分なスラッシュが含まれます。たとえば"path": "${file.original_path}${file.name}"のように使えます。これは、たとえば S3 からファイルをインポートし、何らかの変換を行ったあと、同じまたは似たディレクトリー構造のまま再び S3 に保存したい場合に便利です。 -
${file.name}— 処理中のファイル名です。拡張子を含みます。 -
${file.url_name}— スラッグ化されたファイル名です。ファイル名は URL セーフな形式にするため、音訳とサニタイズが行われます。非 Latin 文字は Latin の同等文字に変換され(例:
café.jpg→cafe.jpg、бубу.mov→bubu.mov)、空白や句読点はハイフンに置き換えられます。連続する非識別文字は 1 つのハイフンにまとめられることがあります。警告非 Latin 文字は Latin の同等文字に音訳され、その他の複雑な文字や特殊記号はハイフンに置き換えられるため、ユーザーの元のマシンでは起きていなかったファイル名の衝突が発生する可能性があります。これを避けるには、必ず
${file.url_name}を${unique_prefix}または${file.md5hash}と組み合わせて使用してください。 -
${file.basename}— 処理中のファイル名です。拡張子は含みません。これにより、fieldsのように Assembly 単位ではなく、ファイルごと に動的な処理を行えます。 -
${file.url_basename}— スラッグ化されたファイルのベース名です(拡張子を除いたファイル名)。ファイル名は URL セーフな形式にするため、音訳とサニタイズが行われます。非 Latin 文字は Latin の同等文字に変換され(例:
café.jpg→cafe.jpg、бубу.mov→bubu.mov)、空白や句読点はハイフンに置き換えられます。連続する非識別文字は 1 つのハイフンにまとめられることがあります。警告非 Latin 文字は Latin の同等文字に音訳され、その他の複雑な文字や特殊記号はハイフンに置き換えられるため、ユーザーの元のマシンでは起きていなかったファイル名の衝突が発生する可能性があります。これを避けるには、必ず
${file.url_basename}を${unique_prefix}または${file.md5hash}と組み合わせて使用してください。 -
${file.user_meta.*}— tus アップロードまたは Robot の設定で指定した、ファイルごとのカスタムメタデータです。継承ルールと完全な例については、カスタムメタデータ を参照してください。 -
${file.ext}— ファイル拡張子です。 -
${file.size}— ファイルサイズ(バイト)です。 -
${file.type}— Transloadit が検出し、Assembly Status JSON で公開する大まかなファイルカテゴリです。たとえば、image、video、audio、pdf、office、xls、swf、documentなどです。粗い分類が必要な場合や、既存のワークフローとの互換性が必要な場合に使ってください。より堅牢に内容を判定したい場合は、${file.mime}を推奨します。 -
${file.mime}— Transloadit が検出したファイルの MIME タイプです。通常のアップロードフローでは、サーバーサイドのメタデータ抽出中に検出されるのが一般的です。これは、クライアントやブラウザーが元々報告した MIME タイプと異なる場合があります。コンテンツタイプによる分岐にはこれを優先し、可能であればimage/*、video/*、audio/*のような MIME ファミリー一致を使用してください。 -
${file.md5hash}— ファイルの MD5 ハッシュです。これはファイル名だけでなく、ファイル内容に対するハッシュです。 -
${file.*}— 最終 results 配列で利用可能なファイルプロパティーです。例:${file.meta.width}。すべてのメタキーがすべてのファイルタイプで利用できるわけではありません。 -
${fields.*}— アップロードと一緒に送信されたフィールドです。たとえば、Uppy で
fields: ['myvar']を許可する設定にしたフォーム送信で、フォームに<input type="hidden" name="myvar" value="1" />のようなタグがある場合、${fields.myvar}には1という値が入ります。あるいは、次のようにプログラムからフィールドを設定することもできます。
{ "steps": { "store": { "use": "encoded", "robot": "/s3/store", "credentials": "YOUR_S3_CREDENTIALS_NAME", "path": "${assembly.id}/${fields.subdir}/356" } }, "fields": { "subdir": "bar" } }競合した場合は、フォームフィールド由来の変数が、
fieldsキー由来の変数より優先されます。Smart CDN リクエストでは、代わりに URL から同じ名前空間が設定されます。クエリーパラメーターは
${fields.*}の値になり、Template 名の後ろのパスは、先頭スラッシュなしの暗黙的な${fields.input}の値になります。たとえば、https://my-app.tlcdn.com/image-template/images/canoe.jpg?w=640では、${fields.input}がimages/canoe.jpgとして、${fields.w}が640として渡されます。したがって、${fields.input}を 🤖/s3/import のpathとして使うと、オブジェクトキーimages/canoe.jpgを読み取ります。この URL 由来の設定経路は、アップロード時のフォームフィールドや、前述の Assembly のfieldsキーとは別です。 -
${browser.wanted_image_format}— リクエスト元クライアントのAcceptヘッダーが優先する画像形式です。"avif"、"webp"、"jpg"のうち、正の品質(q)重みが最も高いものに解決されます。重みが同じ場合は、その順序が優先されます。*/*やimage/*のようなワイルドカードのメディアレンジは、クライアントが AVIF または WebP を選好していることを意味しません。ヘッダーがない、空である、またはワイルドカードのみの場合は、"jpg"に解決されます。JPEG も候補に含まれるため、image/avif;q=0.2,image/jpeg;q=1は"jpg"に解決されます。この変数は通常の Assembly でも利用できます。意味のある
Acceptヘッダーがない SDK および API リクエストでは、"jpg"フォールバックがよく使われます。代わりに Smart CDN のエッジが、信頼できる事前正規化済みのx-tl-image-formatヘッダーを設定することもあります。このヘッダーは同じ"avif"、"webp"、"jpg"のいずれかの値に解決され、Acceptを再解析する必要はありません。"jpg"フォールバックが表すのは、入力ファイルではなくクライアントの対応状況です。🤖/image/resize を使う場合、明示的なモダン形式の選好がないクライアントでは入力形式を維持できるよう、このフォールバックをnullにマッピングしてください。これにより、不要に入力を JPEG へ再エンコードせずに、透過とアニメーションを保持できます。 -
${Date.now()}— 現在の日時を、UNIX epoch からの経過ミリ秒数で表した値です。UNIX epoch は 1970 年 1 月 1 日 UTC の午前 0 時に定義されています。厳密にはこれは変数ではなく、動的コード評価 を使用します。
user_meta を使うカスタムメタデータ
任意の user_meta パラメーターを使うと、Step が出力する各ファイルに
JSON 値を付加できます。後続の Step では、それらを ${file.user_meta.key} として読み取れます。値にはネストしたオブジェクトや配列を含められます。これらはファイルの内容を変更せず、file.id や file.meta のような信頼済みプロパティーを上書きすることもありません。
処理 Step では、値は Robot の実行後、出力された各ファイルごとに個別に評価されます。user_meta 内では、${file.*} は最初の入力ファイルを、${result.*} は出力されたファイルを指します。たとえば、/file/hash が出力したハッシュを ${result.meta.hash} で参照し、カスタムメタデータに格納できます。使えるのは、その時点ですでに利用可能な出力プロパティーだけです。これは後続のメタデータ抽出や一時保存の前に行われます。${result.*} は通常の Robot パラメーターでは利用できません。
:original(/upload/handle)では、値はメタデータ抽出前に各アップロードごとに個別に評価されます。そこで抽出済みハッシュや寸法に依存しないでください。アップロードしたファイルのハッシュを保持するには、以下のように最初の処理 Step で
${file.md5hash} を代入してください。
継承の挙動は Robot によって異なります。/image/resize は最初の入力ファイルからメタデータを引き継ぎますが、複数入力のマップを結合することはありません。/html/convert のように新しい出力ファイルを生成する Robot では、そのマップを継承しない場合があります。そのような Step では、必要なキーを
${file.user_meta.key} で明示的に設定してください。現在の Step の値は、その出力ファイル上にすでにある同名のトップレベルキーを置き換えます。ネストしたオブジェクトは置換され、ディープマージはされません。
アップロード画像のハッシュを保持
この例を使う前に、名前付き S3 Template 認証情報を設定し、リクエストフィールド
customer を指定してください。resize Step は入力画像のハッシュを取得し、export Step はリサイズ後ファイルのハッシュではなく、その保存済みの値を読み取ります。
{
"steps": {
":original": {
"robot": "/upload/handle",
"user_meta": {
"stage": "uploaded"
}
},
"resized": {
"use": ":original",
"robot": "/image/resize",
"width": 640,
"height": 640,
"resize_strategy": "fit",
"result": true,
"user_meta": {
"source_md5": "${file.md5hash}",
"stage": "resized",
"source": {
"name": "${file.name}"
},
"tags": [
"profile",
"${fields.customer}"
]
}
},
"exported": {
"use": "resized",
"robot": "/s3/store",
"credentials": "YOUR_S3_CREDENTIALS_NAME",
"path": "${file.user_meta.source_md5}/${unique_prefix}/${file.url_name}"
}
}
}
resized の結果には user_meta が含まれ、その中に
source_md5、更新後の stage、ネストした source オブジェクト、tags 配列が含まれます。${unique_prefix} により、同一のアップロードであっても export パスの一意性を保てます。ファイルオブジェクトでは、このメタデータを
Assembly Status レスポンス で確認できます。これに秘密情報を入れないでください。
適切なメタデータスコープの選択
fields には Assembly レベルのリクエスト値が入ります。meta には検出されたファイルメタデータが入ります。user_meta には、tus アップロードで渡した追加メタデータを含む、ファイルごとのカスタム値が入ります。単純な Assembly Variable を通す場合、値がない場合や
null の場合は空文字列として読み取られます。一方、単独の数値またはブール値の変数は型が維持されます。
Assembly Variable の例
ファイルの保存場所が気に入らないとします。デフォルトでは、Transloadit は何も上書きしないよう配慮しています。すべての エクスポート Robot には
path パラメーターがあり、そのデフォルト値は
"${unique_prefix}/${file.url_name}" です。その結果、保存先は
"f2/d3eeeb67479f11f8b091b04f6181ad/my-file-name.png" のようになります。
たとえば、このパラメーターの値を "${previous_step.name}/${file.id}.${file.ext}" に変更すると、パスは "video-step-name/a8d3eeeb67479f11f8b091b04f6181ad.png" のようになります。
すべての Assembly Variable が同じではなく、保存先の決定に単独で使うのに適した、より一意性の高いものもあります。以下は、一意性が低いものから高いものへ並べた例です。
${file.ext}は多くのファイルで同じです${file.url_name}は、特にユーザーや時間をまたぐと衝突する可能性が高く、たとえばavatar.jpgのようになります${previous_step.name}は同じ Step の結果であるすべてのファイルで同じです${assembly.id}は 1 つの Assembly 内のすべてのファイルで 同じ です${file.id}と${unique_prefix}は、各ファイルごとに一意 です
Assembly Variable だけではユースケースに対して柔軟性が足りない場合は、動的コード実行 も利用できます。これは /script/run Robot を使う方法で、Assembly Instructions から JavaScript を評価できます。