ファイルのフィルタリング
🤖/file/filter は指定した条件に基づいて、ファイルを異なるエンコード用の Step に振り分けます。

この Robot は、高度なファイル変換ワークフローを構築するための if/else 条件として利用できます。アップロードされたファイルをメタデータに応じて絞り込み、振り分けられます。
この Robot には、二つの動作モードがあります。
- それぞれ 3 個の要素を持つ配列で条件を構成します。例:
["${file.size}", "<=", "720"] - JavaScript で条件を記述します。例:
${file.size <= 720}。動的評価も参照してください。
/file/filter の Step ですべての入力ファイルを変更せずに通過させるには、accepts と
declines を未設定のままにするか、null に設定してください。この用途で "accepts": "true" は使用しないでください。通常の文字列が JavaScript 式として扱われるのは、"${true}" のように ${...} 形式を使用している場合のみです。
JavaScript を渡すと、必要に応じて複雑なロジックを実装できます。ただし、条件の配列を組み合わせる場合よりも低速で、🤖/script/runを通じて呼び出しごとに課金されます。
配列による条件
accepts パラメーターと declines パラメーターには、それぞれ三つの要素を持つ配列の配列を設定できます。
- 値またはジョブ変数。例:
${file.mime} - 次のいずれかの演算子:
=、==、===、<,>、<=,>=、!=、!==、regex、!regex、includes、!includes、empty、!empty - 値またはジョブ変数。例:
50または"foo"
例:
[["${file.meta.width}", ">", "${file.meta.height}"]][["${file.size}", "<=", "720"]][["${file.size}", ">", "20mb"]][["720", ">=", "${file.size}"]][["${file.mime}", "regex", "image"]]
${file.mime} と照合する場合、その値は通常、クライアントやブラウザーが報告する MIME タイプだけではなく、通常のアップロードフローで Transloadit がサーバー側で抽出したメタデータに基づきます。このため、/file/filter は、誤ったラベルが付いたファイルの拒否に適しています。ファイルのコンテナーや使用される検出ツールによっては、一部の形式が image/heic や image/heif など、密接に関連する MIME タイプとして報告される場合があります。
ブラウザーで安定して表示できる形式だけを許可する場合は、広範な ^image/ ルールではなく、^(image/jpeg|image/png|image/gif|image/webp|image/avif)$ のような明示的な許可リストを使用してください。
数値比較(<, >、<=, >=)では、"20mb"、"1gb"、"512kb" など、人が読みやすいバイト値を使用できます。これらは二進数ベース(1024 基準)の倍率を使用します。対応する単位:b、kb、mb、gb、tb、pb(および対応する IEC 単位の kib、mib、gib、tib、pib)。
includes 演算子と !includes 演算子は、配列または文字列に使用できます(文字列では部分文字列の判定を行います)。
null 値や、存在しない値(音声ファイルのメタデータに video_codec プロパティがない場合など)と照合するには、代わりに ""(空文字列)と照合してください。将来的には null との適切な照合に対応する予定ですが、現時点では後方互換性を損なわずに実現するのは困難です。
JavaScript による条件
accepts パラメーターと declines パラメーターには、それぞれブール値を返す JavaScript の文字列を設定できます。
例:
${file.meta.width > file.meta.height}${file.size <= 720}${/image/.test(file.mime)}${Math.max(file.meta.width, file.meta.height) > 100}
前述のとおり、この処理は🤖/script/runを通じて課金されます。使用できる構文や動作の詳細については、動的評価も参照してください。
使用例
20 MB を超えるファイルを拒否する例:
{
"steps": {
"filtered": {
"declines": [
[
"${file.size}",
">",
"20mb"
]
],
"error_msg": "File size must not exceed 20 MB",
"error_on_decline": true,
"robot": "/file/filter",
"use": ":original"
}
}
}パラメーター
interpolateboolean | Record<string, boolean>処理設定の各フィールドで Assembly Variables を展開するかどうかを制御します。
デフォルトでは、Robot の処理設定のほとんどのフィールドで Assembly Variables が展開されます。すべての設定フィールドをリテラルテキストとして扱うには、このパラメーターを
falseに設定してください。特定のフィールドだけをリテラルテキストとして扱うには、そのフィールドのパスをfalseに設定してください。デフォルトでリテラルとして扱われる Robot 固有のフィールドで展開を有効にするには、このパラメーターをtrueに設定するか、そのフィールドのパスをtrueに設定してください。pathのようなフィールド名を使用してください。ネストされたオブジェクトには、ffmpeg.vfのようなドット区切りのパスを使用してください。output_metaRecord<string, boolean> | boolean | Array<string>算出に多くの CPU リソースを要するメタデータを指定できます。Assembly の処理速度を維持するため、これらはデフォルトで無効になっています。
画像の場合、このオブジェクトに
"has_transparency": trueを追加すると、画像に透明な部分が含まれるかどうかを抽出できます。"dominant_colors": trueを追加すると、画像から 16 進数のカラーコードの配列を抽出できます。画像の場合、
"blurhash": trueを追加すると、画像のプレースホルダーをコンパクトに表す BlurHash 文字列も抽出できます。画像全体の読み込み中に、ぼかしたプレビューを表示するのに役立ちます。画像の場合、代わりに
"thumbhash": trueを使用すると、base64 エンコードされた ThumbHash をmeta.thumbhashに抽出し、meta.has_alpha(完全に不透明な場合も含め、アルファチャンネルが存在するかどうか)も抽出します。ThumbHash は EXIF の向きを反映したピクセルを表し、アニメーション画像では最初のフレームを使用します。抽出はベストエフォートです。40 メガピクセルを超える画像、非対応の形式、デコードの失敗やデコード処理の上限への到達があった場合、プレースホルダーは生成されません。抽出に成功すると、そのファイルのバイト数の 20% に相当するメタデータ料金が加算されます。無効な場合やハッシュが生成されない場合、ThumbHash の追加料金は発生しません。このオプションは画像を生成する Step に設定してください。たとえば、アップロードされた元画像では
/upload/handle、処理済みの出力では/image/resizeに設定します。/transloadit/storeにのみ設定しても、抽出は要求されません。ストレージは生成元のメタデータを保持します。Transloadit Storage は生成されたハッシュをその不変のバージョンとともに永続化し、保存済みの結果やネイティブのアセット読み取り時に返します。S3 への直接アップロードではプレースホルダーは生成されません。プレースホルダーには画像情報が含まれるため、画像全体と同じアクセス制御で保護してください。動画の場合、
"colorspace": trueパラメーターを追加すると、出力動画の色空間を抽出できます。動画の場合、
"interlaced": trueを追加すると、インターレース動画かどうかも検出できます。これは、低コストの ffprobe のfield_orderフラグと、ソースの先頭フレームに対する処理範囲を制限したidetサンプリング処理を組み合わせ、file.metaの下にinterlaced、field_order、診断用のinterlace_detectionオブジェクトを出力します。この処理は計算コストが高く、それに応じて課金されます。音声の場合、
"mean_volume": trueを追加すると、音声ファイルの平均音量を表す単一の値を取得できます。また、
falseに設定すると、メタデータの抽出をスキップしてトランスコードを高速化できます。user_metaRecord<string, any>(デフォルト:{})出力される各ファイルに、ファイルの内容を変更せずにカスタム JSON メタデータを追加します。ネストしたオブジェクトと配列に対応しています。
継承の動作は Robot によって異なります。値は出力ファイルの既存の
user_metaとマージされ、一致するトップレベルのキーは現在の Step によって置き換えられます。Robot が新しい出力を作成する場合は、必要なキーを明示的に割り当ててください。処理 Step では、
${file.*}は最初の入力を、${result.*}は出力されるファイルを参照します。値は Robot の実行後、後続のメタデータ抽出と一時保存の前に、出力ごとに評価されます。:originalでは、メタデータ抽出の前にアップロードごとに値が評価されます。後続の Step は
${file.user_meta.key}を読み取ります。完全な例と継承ルールについては、カスタムメタデータ を参照してください。resultboolean(デフォルト:false)この Step の結果を Assembly Status JSON に含めるかどうか
queuebatchqueue を 'batch' に設定すると、このステップのジョブの優先度を手動で下げ、キューの待ち時間がゼロである必要のないジョブが優先ジョブスロットを消費しないようにします。
force_acceptboolean(デフォルト:false)通常は無視するファイルタイプを Robot に強制的に受け入れさせます。
デフォルトでは、Robot は認識できないファイルを無視します。たとえば、🤖/video/encodeは入力画像を無視します。
force_acceptパラメーターをtrueに設定すると、Robot に渡されたすべてのファイルを強制的に受け入れさせることができます。通常、この設定はエラーにつながるため、デバッグやエッジケースへの対処にのみ使用してください。ignore_errorsboolean | Array<meta | execute>(デフォルト:[])処理の特定のフェーズでエラーを無視します。
このパラメーターを
["meta"]に設定すると、Robot はメタデータ抽出中のエラーを無視します。このパラメーターを
["execute"]に設定すると、Robot はメイン実行フェーズ中のエラーを無視します。このパラメーターを
trueに設定すると、["meta", "execute"]と同じ動作になり、両方のフェーズでエラーを無視します。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 には任意の名前を付けられます。ただし、
acceptsnull | string | Array<[string | string | number | null | Array<string | string | number | null>, "=" | "==" | "===" | "<" | ">" | "<=" | ">=" | , string | string | number | null | Array<string | string | number | null>]>少なくとも一つの要件に一致するファイルは受け入れられ、それ以外は拒否されます。値が
nullの場合は、すべてのファイルが受け入れられます。配列が空の場合は、どのファイルも受け入れられません。Step ですべてのファイルを通過させるには、このパラメーターを省略するか、nullに設定してください。例:[["${file.mime}", "==", "image/gif"]][["${file.size}", "<", "5kb"]]数値比較(
<,>、<=,>=)では、"20mb"、"1gb"、"512kb"など、人が読みやすいバイト値を使用できます。condition_typeパラメーターが"and"に設定されている場合、ファイルを受け入れるにはすべての要件に一致する必要があります。acceptsとdeclinesの両方が指定されている場合、declinesの条件よりも先にacceptsの要件が評価されます。declinesnull | string | Array<[string | string | number | null | Array<string | string | number | null>, "=" | "==" | "===" | "<" | ">" | "<=" | ">=" | , string | string | number | null | Array<string | string | number | null>]>少なくとも一つの条件に一致するファイルを拒否し、それ以外のファイルを受け入れます。値が
nullまたは空の配列の場合、ファイルは拒否されません。例:[["${file.size}", ">", "1024"]][["${file.size}", ">", "20mb"]]数値比較(
<,>、<=,>=)では、"20mb"、"1gb"、"512kb"など、人が読みやすいバイト値を使用できます。condition_typeパラメーターを"and"に設定した場合、すべての条件に一致するファイルのみを拒否します。acceptsとdeclinesの両方が指定されている場合、declinesの条件よりも先にacceptsの要件が評価されます。condition_typeand | or(デフォルト:"or")acceptsまたはdeclinesの配列の各要素を評価する際の条件タイプを指定します。"or"または"and"を指定できます。error_on_declineboolean(デフォルト:false)trueに設定されていて、一つ以上のファイルが拒否された場合、Assembly は停止し、エラーとしてマークされます。error_msgstring(デフォルト:"One of your files was declined")ファイルが拒否され、
error_on_declineがtrueに設定されている場合に、Uppy などを通じてユーザーに表示されるエラーメッセージです。
デモ
- Service to generate a slideshow from AI-filtered images (English)
- Automatic explicit content detection service (English)
- Automatic image recognition service (English)
- Service to automatically filter out large video files (English)
- Rotate image to portrait mode if horizontal (English)
- Service to automatically filter files to separate encoding Steps (English)
- Service to automatically filter out files smaller than 1KB (English)
- Service to only resize larger images when resizing files (English)
- Service to reject files containing copyright (English)
- Service to preserve transparency across image types (English)
関連ブログ記事
- ファイルフィルタリング用の新しい /file/filter Robot を公開
- ファイル処理向けの新しい Robot と機能のご紹介
- jQuery SDK 2.1.0 をリリース!
- jQuery SDK 2.4.0:安定性向上のための重要な修正
- テストと重要なパッチによる jQuery SDK の改善
- Assembly を高速化する大幅なパフォーマンス改善
- 安全なアップロードを実現する新しいウイルススキャン Robot の紹介
- 今後の Transloadit のお客様向け新料金モデル
- Transloadit、動画エンコードを高速化する Turbo Mode を公開
- 最適化で効率化する Dropbox から SFTP へのファイル転送
- チュートリアル:Transloaditでのファイルフィルタリングとウイルススキャン
- Tech preview:メディア処理を強化する新しい AI Robot
- Transloadit の 2021年の節目と進歩
- Transloadit で字幕をスタイリングする 3 つのアイデア
- 音声と動画の連結を高速化
- Transloadit で著作権メタデータを確認し画像に透かしを追加
- Transloadit による NSFW 画像の自動フィルタリング
- 1つの Assembly で低解像度画像を拡大・補正