ウェブブラウザーへのファイル配信
🤖/file/serve はウェブブラウザーにファイルを配信します。

Transloadit でファイルをオンザフライで変換する場合、この Robot を使うと、エンドユーザーに CDN 経由で配信する Step を
Template 内から選び、配信ファイルのヘッダーなどの追加情報も設定できます。たとえば、結果のキャッシュコピーを保持する期間を CDN に提示できます。デフォルトでは、ブラウザーには結果を 72 h(259200 秒)、CDN にはコンテンツを 24 h(86400 秒)キャッシュするよう指示します。両方の値をまとめて変更するには、cache_duration パラメーターを使います。
🤖/file/serve は、当社の Assembly エンジンと
HTTP によるファイル配信をつなぐ役割のみを担います。use パラメーターで一連の
Step から適切な結果を選び、元のコンテンツにヘッダーを設定できます。その役割はここまでです。以降は 🤖/tlcdn/deliver が元のコンテンツを世界中に配信し、エンドユーザーが https://my-app.tlcdn.com/resize-img/canoe.jpg?w=500 などのリクエストを行う際に、その近くでコンテンツが確実にキャッシュされるようにします。🤖/tlcdn/deliver は
Assembly Instructions には含まれませんが、キャッシュコピーの配信に帯域幅料金が発生するため、請求書に表示される場合があります。🤖/file/serve の料金は、CDN にキャッシュコピーがなく、元のコンテンツの再生成をリクエストした場合にのみ発生します。キャッシュ設定によっては、ファイルと変換の組み合わせごとに、月に一度、または年に一度だけとなる場合もあります。
理論上は 🤖/file/serve を HTML ファイル内で直接使えますが、強く非推奨とします。サイトの人気が高まり、/file/serve が処理するメディア URL に 1,000,000 回アクセスされると、画像のサイズ変更処理も新たに 1,000,000 回発生するためです。CDN を介することで、そのキャッシュ機能により、エンコード料金とレイテンシーを低く抑えられます。
また、鮮度と効率のバランスを取りながら CDN エッジサーバーでのコンテンツのキャッシュと無効化を制御するために、キャッシュ用ヘッダーと cache-control ディレクティブの設定も検討してください。
署名付き URL による Smart CDN のセキュリティ
署名付き Smart CDN URL を活用すると、当社のエンコードプラットフォームの不正利用を防げます。以下は当社の Node SDK を使った簡単な Node.js の例です。ほかの言語や SDK の例もあります。
// yarn add @transloadit/node
// or
// npm install --save @transloadit/node
import { Transloadit } from '@transloadit/node'
const transloadit = new Transloadit({
authKey: 'YOUR_TRANSLOADIT_KEY',
authSecret: 'YOUR_TRANSLOADIT_SECRET',
})
const url = transloadit.getSignedSmartCDNUrl({
workspace: 'YOUR_WORKSPACE',
template: 'YOUR_TEMPLATE',
input: 'image.png',
urlParams: { height: 100, width: 100 },
})
console.log(url)
これにより、認証パラメーターを含む署名付き Smart CDN URL が生成され、変換エンドポイントへの不正アクセスを防ぎます。
新規の連携には、最新の sig + exp 形式を使ってください。従来の s 署名は非推奨です。また、有効期限までの期間は、署名付きの結果を実際にキャッシュできる期間でもあります。有効期間を短くするとアクセス制御が厳格になり、長くするとキャッシュの再利用が進み、エンコード量が減ります。
詳細情報
- コンテンツ配信
- 🤖/file/serve の料金
- 🤖/tlcdn/deliver の料金
- ファイルプレビュー機能についてのブログ記事
使用例
ブラウザーと CDN のキャッシュ期間を明示的に指定して、変換済みファイルを配信する例:
{
"steps": {
"resized": {
"height": 450,
"resize_strategy": "fit",
"robot": "/image/resize",
"use": ":original",
"width": 800
},
"served": {
"cache_duration": 86400,
"robot": "/file/serve",
"use": "resized"
}
}
}パラメーター
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 には任意の名前を付けられます。ただし、
cache_durationstring | number配信ファイルをキャッシュする期間を秒単位で指定する任意の設定です。設定すると、
Cache-Controlヘッダーのmax-age(ブラウザーキャッシュ)とs-maxage(共有/CDN キャッシュ)の両ディレクティブにこの値が使われ、デフォルト値を上書きします。たとえば、cache_durationを43200に設定すると、ファイルは 12 時間キャッシュされます。CDN でのデータ保持期間の制御に役立ちます。たとえば、一時ファイルが 24 時間後に削除される場合、
cache_durationを86400に設定すると、キャッシュコピーもその期間内に期限切れになるようにできます。download_namestringこの Unicode ファイル名を使って添付ファイルとして配信します。空または省略した場合はインライン配信を維持します。ファイルのバイト列や Range のサポートを変更せずに、Content-Disposition ヘッダーを上書きします。
headersRecord<string, string>(デフォルト:{"Access-Control-Allow-Headers":"X-Requested-With, Content-Type, Cache-Control, Accept, Content-Length, Transloadit-Client, Authorization, Range, If-Range","Access-Control-Allow-Methods":"POST, GET, PUT, DELETE, OPTIONS","Access-Control-Allow-Origin":"*","Access-Control-Expose-Headers":"Transloadit-Assembly-URL, Content-Range, Content-Length, Accept-Ranges","Cache-Control":"public, max-age=259200, s-maxage=86400","Content-Type":"${file.mime}; charset=utf-8","Transloadit-Assembly":"…","Transloadit-RequestID":"…","Accept-Ranges":"bytes"})ファイルを CDN や Web ブラウザーに配信する際に設定するヘッダーのリストを含むオブジェクトです。たとえば
{ FileURL: "${file.url_name}" }などを指定すると、デフォルト値にマージして上書きします。利用可能な任意の Assembly Variable を含められます。Accept-Ranges: bytesヘッダーは、メディア再生時にタイムライン上の任意の位置に移動できるよう、HTTP 範囲リクエストに対応していることを通知します。これは、Transloadit のストレージバックエンド(S3、GCS など)がすべて Range リクエストヘッダーに従うことに依存しています。CORS ヘッダーでは、クロスオリジンの範囲リクエストを許可するためにAccess-Control-Allow-HeadersにRangeとIf-Rangeを含めます。また、ブラウザーの JavaScript から値を読み取れるように、Access-Control-Expose-Headersを通じてContent-Range、Content-Length、Accept-Rangesを公開します。