Amazon S3 にファイルをエクスポート
🤖/s3/store は、エンコード結果を Amazon S3 にエクスポートします。

Amazon S3 を初めて利用する場合は、独自の S3 バケットを使用するチュートリアルをご覧ください。
S3 バケット内の結果ファイルの URL は、Assembly Status JSON に返されます。URL が返されても、非公開オブジェクトが公開されたり、読み取りアクセス権が付与されたりするわけではありません。S3 バケットでバージョニングを有効にしている場合は、ファイルのバージョン ID が meta.version_id 内に返されます。
非公開バケットは明示的に設定してください。 Robot のデフォルトの acl は、引き続き "public-read" です。非公開バケットでは、acl: "bucket-default" を設定し、ACL ヘッダーや grant ヘッダーを指定しないでください。これにより、生成される ACL ヘッダーが省略され、ACL が無効な Bucket owner enforced の Object Ownershipでも動作します。S3 Block Public Access は有効のままにしてください。acl: "private" を設定しても ACL は送信されるため、省略した場合と同じにはなりません。
DNS に準拠したバケット名を使用してください。 AWS のバケット命名規則に従ってください。url_prefix パラメーターは返される URL を変更しますが、バケットやそのアクセス許可は変更しません。
アクセスの制限
保存先のバケットとオブジェクトプレフィックスにアクセスを限定した、専用の AWS ID を使用してください。AWS ルートアクセスキーは使用しないでください。その ID のアクセスキー ID、シークレットアクセスキー、バケット名、リージョンを、それぞれ key、secret、bucket、bucket_region として Template 認証情報 に保存し、credentials でその認証情報名を参照してください。信頼できるバックエンド連携では、代わりにこれらのパラメーターを直接指定できます。ブラウザー側の処理設定で AWS のシークレットを公開しないでください。
以下は、その専用 ID にアタッチするアイデンティティベースの IAM ポリシーであり、バケットポリシーではありません。意図的に Principal を含めていません。{BUCKET_NAME} を置き換え、Robot の path には uploads/ で始まる値を使用してください。または、ポリシーのプレフィックスとパスの両方を合わせて変更してください。
この例は、bucket_region の明示的な指定、acl: "bucket-default" の設定、ACL ヘッダーおよび grant ヘッダーなし、タグなし、S3 マネージド暗号化(SSE-S3)という条件でのアップロードと、失敗したマルチパートアップロードのクリーンアップを対象としています。この設定でも、既存のバケットポリシー、組織の制御、エンドポイントポリシーによってアクセスが拒否される場合があります。
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "UploadAndAbortWithinPrefix",
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
"Resource": "arn:aws:s3:::{BUCKET_NAME}/uploads/*"
}
]
}
アップローダーは、PutObject、または CreateMultipartUpload、UploadPart、CompleteMultipartUpload の組み合わせを使用します。マルチパートアップロードが失敗すると、AbortMultipartUpload が実行される場合があります。AWS では、正常なアップロード操作に対応する権限は s3:PutObject です。書き込みアクセスでは、既存のオブジェクトキーを上書きできます。追加専用ではありません。一意のオブジェクトパスを選び、復旧に備えてバージョニングの利用を検討してください。
AWS の操作別の権限リファレンスに従い、使用する機能に必要な権限だけを追加してください。
bucket_regionを明示的に指定しない場合、リージョンの検出にs3:GetBucketLocationと、フォールバック用のs3:ListBucketが必要になることがあります。これらの権限の対象は、オブジェクトのサフィックスを含まないバケット ARN、arn:aws:s3:::{BUCKET_NAME}です。正しいリージョンを指定すれば、これらの検出リクエストを回避できます。- ACL ヘッダーや grant ヘッダーには
s3:PutObjectAclが必要です。タグには、許可されたオブジェクトプレフィックスに対するs3:PutObjectTaggingが必要です。bucket-defaultを指定しても、headersで指定した ACL ヘッダーや grant ヘッダーは削除されません。 - 非公開の結果をダウンロードするには、別途読み取りの認可が必要です。
sign_urls_forで生成した URL であっても、署名に使用する ID に適切な読み取り権限が必要です。
暗号化の上書き設定が送信されない場合、S3 はバケットの暗号化設定を適用します。headers を通じて、x-amz-server-side-encryption: aws:kms と x-amz-server-side-encryption-aws-kms-key-id を使用し、SSE-KMS を要求できます。バケットのデフォルト暗号化またはリクエストヘッダーで SSE-KMS が選択されている場合、アップロードに使用する ID には、該当キーに対する kms:GenerateDataKey が必要です。マルチパートアップロードでは、さらに kms:Decrypt が必要です。カスタマーマネージドキーでは、対応する KMS キーポリシーでこれらの権限を付与してください。上記の基本的な S3 ポリシーには、これらの権限は含まれていません。kms:* や sts:* を一括で許可しないでください。
有効期間の短い AWS 認証情報は、互いに対応する key、secret、session_token の一式です。信頼できるバックエンドで三つすべてを取得・更新し、そのバックエンドが Assembly を作成するときにまとめて指定してください。バックエンドから Robot の処理設定に直接渡すことも、Template 認証情報 API を通じてまとめて保存・更新することもできます。三つともブラウザー側の処理設定には含めないでください。セッショントークンだけを置き換えても、期限切れのアクセスキーは更新されません。この Robot は、指定された認証情報を S3 に渡します。ロールの引き受けや期限切れの認証情報の更新は行いません。アップロード中は、一時的な認証情報を有効に保ってください。
使用例
アップロードしたファイルを S3 バケット内の my_target_folder にエクスポートする例:
{
"steps": {
"exported": {
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "my_target_folder/${unique_prefix}/${file.url_name}",
"robot": "/s3/store",
"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 には任意の名前を付けられます。ただし、
credentialsstringTransloadit アカウントで対応する Template 認証情報 を作成し、その Template 認証情報 の名前をこのパラメーターの値に指定してください。この認証情報には、S3 の
bucket、key、secret、bucket_regionの値を設定します。常に Template 認証情報 の使用を推奨していますが、動的な認証情報が必要な用途では、Template 認証情報 は静的な性質のため扱いにくい場合があります。その場合は、代わりに次のパラメーターを使用できます:
"bucket"、"bucket_region"(例:"us-east-1"または"eu-west-2")、"key"、"secret"。pathstring(デフォルト:"${unique_prefix}/${file.url_name}")ファイルの保存先パスです。利用可能な任意の Assembly Variablesを含められます。ディレクトリを指すパスは指定できません。
url_prefixstring(デフォルト:"http://{bucket}.s3.amazonaws.com/")返される URL に使用する URL プレフィックスです。たとえば、
"http://my.cdn.com/some/path/"などを指定します。aclauthenticated-read | aws-exec-read | bucket-default | bucket-owner-full-control | bucket-owner-read | private | public |(デフォルト:"public-read")このファイルに使用する ACL です。AWS のオブジェクト用の既定 ACL に対応しています。他の S3 互換プロバイダーでは、対応する ACL が異なる場合があります。デフォルトは引き続き
"public-read"であり、S3 Block Public Access や ACL の無効化と競合する可能性があります。現在の非公開バケットでは、"bucket-default"を明示的に設定して、生成される ACL ヘッダーを省略し、headersに ACL ヘッダーや grant ヘッダーを指定しないでください。"private"を指定しても ACL は送信されます。check_integrityboolean(デフォルト:false)ファイルのチェックサムを計算して送信し、アップロード後に S3 がファイルの整合性を検証できるようにします。これにより、まれに発生するファイル破損の問題に対処できる場合があります。
整合性の検証は、特に大きなファイルでは CPU に高い負荷がかかる場合があるため、このオプションを有効にすると全体の実行時間が長くなります。
headersRecord<string, string>(デフォルト:{"Content-Type":"${file.mime}"})S3 上のこのファイルに設定するヘッダーの一覧を含むオブジェクトです。たとえば、
{ FileURL: "${file.url_name}" }などを指定します。利用可能な Assembly Variables も含められます。使用できるヘッダーの一覧はこちらをご覧ください。オブジェクトのメタデータは
x-amz-meta-*ヘッダーで指定できます。これらのヘッダーは ASCII 以外の文字を含むメタデータ値には対応していないことに注意してください。tagsRecord<string, string>(デフォルト:{})オブジェクトのタグ付けにより、ストレージを分類できます。オブジェクトには最大 10 個のタグを関連付けられます。同じオブジェクトに関連付けるタグのキーは一意である必要があります。
hoststring(デフォルト:"s3.amazonaws.com")使用するストレージサービスのホストです。Amazon S3 以外で、互換 API を持つストレージサービス(hosteurope.de など)を使用する場合にのみ設定が必要です。デフォルトのプロトコルは HTTP です。それ以外のプロトコルを使用する場合は明示的に指定する必要があります。たとえば、ホストの先頭に
https://またはs3://を付けると、それぞれのプロトコルを使用できます。no_vhostboolean(デフォルト:false)カスタムホストを使用していてアクセス拒否エラーが発生する場合は、
trueに設定してください。sign_urls_forstring | numberこのパラメーターを指定すると、結果の JSON の
signed_urlプロパティとsigned_ssl_urlプロパティに署名付き URL が含まれます。このパラメーターに設定する数値は、URL の有効期間(秒)です。このパラメーターを使用しない場合、URL への署名は行われません。session_tokenstringS3 または R2 などの互換サービスへの今回のアップロード用に指定した、一時的なアクセスキー ID とシークレットアクセスキーに対応するセッショントークンです。この Robot はロールの引き受けや認証情報の更新を行いません。これらの認証情報は、アップロード中も有効である必要があります。
デモ
関連ブログ記事
- API アップデート:わかりやすさ向上のための Robot 名変更
- Transloadit における S3 PUT リクエストの不整合への対処
- /s3/store Robotの「url_prefix」パラメーターのご紹介
- SFTP Robot の正式公開と新しいホームページのお披露目
- すべての Robot で Assembly Variable の利用範囲が拡大
- 公式 S3 CLI への切り替えでファイルエクスポートを強化
- S3 障害への対応:修正と割引
- 今後の Transloadit のお客様向け新料金モデル
- No-code real-time video uploading with Bubble & Transloadit (English)
- DigitalOcean Spaces へのファイルエクスポートを簡単に
- FFmpeg と Node.js で音声波形動画を作成する
- 新機能:動画の自動文字起こしと字幕の追加
- Transloadit の 2021年の節目と進歩
- Terraform でのプロビジョニングを改善する API 拡張
- コンテンツのローカライズとは?
- Transloadit 用の S3 バケットを設定する方法
- ドキュメントのページの向きを自動補正
- 画像の背景を自動削除
- AI を使ってテキストから魅力的な画像を生成
- 1つの Assembly で低解像度画像を拡大・補正
- /document/extract で PDF からテキストと画像を抽出
- Cloudinary、Filestack、Mux、Uploadcare からの移行