Amazon S3 からファイルをインポート
🤖/s3/import は、S3 バケットからディレクトリ内のファイルを丸ごとインポートします。

Amazon S3 を初めて利用する場合は、独自の S3 バケットを使用するチュートリアルをご覧ください。
アクセスの制限
Template 認証情報 には専用の AWS 認証情報を使用し、その IAM アイデンティティには必要なバケットとオブジェクトへのアクセスのみを許可してください。次の例は、単一の汎用 S3 バケットから現行のオブジェクトを読み取るためのアイデンティティベースの IAM ポリシーです。バケットではなく、Transloadit に渡す認証情報の所有者である IAM ユーザーまたはロールにアタッチしてください。アイデンティティベースのポリシーには Principal 要素がなく、アタッチ先のアイデンティティに適用されます。
両方の Resource 値に含まれる {BUCKET_NAME} を、使用するバケット名に置き換えてください。バケットレベルのステートメントはオブジェクトの一覧取得とバケットのリージョン検出を許可し、オブジェクトレベルのステートメントはオブジェクトのダウンロードを許可します。AWS の S3 操作に必要なアクセス許可とアイデンティティベースのポリシーとリソースベースのポリシーの違いをご覧ください。
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ReadBucketMetadata",
"Effect": "Allow",
"Action": ["s3:GetBucketLocation", "s3:ListBucket"],
"Resource": "arn:aws:s3:::{BUCKET_NAME}"
},
{
"Sid": "ReadBucketObjects",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::{BUCKET_NAME}/*"
}
]
}
Sid の値は、ステートメントを識別するためのラベルです。正しい bucket_region を指定すると、リージョンの自動検出と、それに必要な s3:GetBucketLocation 権限が不要になります。この例では、バケット全体の一覧取得と読み取りが許可されます。ワークフローで特定のプレフィックスのみを使用する場合は、オブジェクトリソースと一覧取得の条件を絞り込んでください。
この例はアクセスを保証するものではありません。明示的な拒否、組織のポリシー、アクセス許可の境界、クロスアカウントのバケットポリシー、オブジェクトの所有権が結果に影響する場合があります。クロスアカウントアクセスについては、AWS のポリシー評価に関するガイダンスを確認してください。
SSE-KMS で暗号化されたオブジェクトについては、AWS の GetObject ドキュメントで求められるキーの権限も、対象のキーに範囲を限定して IAM アイデンティティと KMS キーポリシーに設定してください。KMS アクションは IAM アイデンティティポリシーと KMS キーポリシーに記述するものであり、S3 バケットポリシーには記述しません。回避策として広範な sts:* または kms:* 権限を付与しないでください。
使用例
path/to/files ディレクトリとそのサブディレクトリからファイルをインポートする例:
{
"steps": {
"imported": {
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "path/to/files/",
"recursive": true,
"robot": "/s3/import"
}
}
}パラメーター
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 | import | execute>(デフォルト:[])処理の特定のフェーズでエラーを無視します。
このパラメーターを
["meta"]に設定すると、Robot はメタデータ抽出中のエラーを無視します。このパラメーターを
["execute"]に設定すると、Robot はメイン実行フェーズ中のエラーを無視します。このパラメーターを
["import"]に設定すると、Robot はソースファイルのインポート中のエラーを無視します。"import"フェーズは、インポート用の Robot でのみ利用できます。このパラメーターを
trueに設定すると、["meta", "import", "execute"]と同じ動作になり、3 つすべてのフェーズでエラーを無視します。force_namestring | Array<string> | null(デフォルト:null)インポートするファイルのカスタム名です。デフォルトでは、インポート元に基づいてファイル名が決まります。
import_on_errorsArray<meta>(デフォルト:[])["meta"]に設定すると、メタデータ抽出でエラーが発生してもファイルをインポートします。ignore_errorsも同様にエラーを無視して Robot の停止を防ぎますが、ファイルはインポートしません。credentialsstringTransloadit アカウントで対応する Template 認証情報 を作成し、その Template 認証情報 の名前をこのパラメーターの値に指定してください。この認証情報には、S3 の
bucket、key、secret、bucket_regionの値を設定します。常に Template 認証情報 の使用を推奨していますが、動的な認証情報が必要な用途では、Template 認証情報 は静的な性質のため扱いにくい場合があります。その場合は、代わりに次のパラメーターを使用できます:
"bucket"、"bucket_region"(例:"us-east-1"または"eu-west-2")、"key"、"secret"。path— 必須string | Array<string>バケット内の特定のファイルまたはディレクトリへのパスです。ファイルを指すパスの場合、そのファイルのみがインポートされます。例:
images/avatar.jpg。末尾のスラッシュ(
/)で示されるディレクトリを指す場合は、そのディレクトリ直下のすべてのファイルをインポートします。例:images/。ディレクトリは再帰的にはインポートされません。サブディレクトリやその下のサブディレクトリからファイルをインポートするには、
recursiveパラメーターを有効にしてください。バケットのルートからファイルをインポートするには、
/を使用してください。オブジェクトキーの先頭にスラッシュは不要です。ネストされたプレフィックス配下のファイルも含めるには、recursiveを有効にしてください。パス文字列の配列を指定して、この Robot を使用する同じ Step で複数のパスをインポートすることもできます。
recursiveboolean(デフォルト:false)trueに設定すると、指定したパスのサブディレクトリやその下のサブディレクトリなどからファイルをインポートできます。ページネーションのパラメーター
page_numberとfiles_per_pageは、適切に使用してください。page_numberstring | number(デフォルト:1)ページネーションのページ番号です。再帰的でないインポートの後方互換性を維持するため、現時点では recursive が
trueに設定されている場合にのみ機能します。大規模なインポートを行う際は、指定したパス内で他のスクリプトがファイルを追加または削除しないようにしてください。そうしないと、ページネーションで予期しない結果が生じる場合があります。
files_per_pagestring | number(デフォルト:1000)ページネーションのページサイズです。再帰的でないインポートでの後方互換性を維持するため、現時点では recursive が
trueの場合にのみ機能します。return_file_stubsboolean(デフォルト:false)trueに設定すると、Robot は実際のファイルをまだインポートせず、後続の Robot がファイルをインポートできる URL を含む空のファイルスタブを返します。これは、🤖/video/ondemand を使用する場合など、後続の Step でインポート処理をより細かく制御する必要がある場合に役立ちます。このパラメーターは、後続のすべての Step がファイルスタブに対応した Robot を使用する場合にのみ設定してください。rangestring | Array<string>ファイルからインポートするバイト範囲を一つ以上指定できます。この機能を使用するには、S3 が範囲リクエストに対応している必要があります。
単一の範囲:
"0-99"のような文字列を指定すると、バイト位置 0 から 99 まで(先頭の 100 バイト)をインポートできます。複数の範囲:
["0-99", "200-299"]のような配列を指定すると、複数の個別の範囲をインポートできます。出力ファイルには、指定したすべての範囲が連結され、連続していない範囲間の隙間はゼロバイト(\0)で埋められます。範囲の指定形式:
"0-99":バイト位置 0 から 99 まで(両端を含む)"100-199":バイト位置 100 から 199 まで(両端を含む)"-100":ファイル末尾の 100 バイト
重要な注意事項:
- S3 はデフォルトで範囲リクエストに対応しています
- 範囲の重複は許可されており、指定どおりに含まれます
- 出力ファイルのサイズは指定した最大のバイト位置となり、隙間はゼロバイトで埋められます
- S3 との互換性を確保するため、各範囲は個別のリクエストで取得されます