Smart CDN によるオンデマンドメディアプレビュー
ファイルブラウザーでは、動画の内容を示すだけなら、動画全体をダウンロードする必要はほとんどありません。サムネイル、音声波形、ファイル種別のアイコンを使えば、はるかに小さなレスポンスで内容を伝えられます。
/file/preview Robotは、こうしたプレビューを生成します。Smart CDN では、プレビューのリクエスト時に処理ワークフローを実行し、結果をキャッシュできます。この記事では、動作するデモ、制限を設けた Template、サーバー側での URL 署名を組み合わせます。
Transloadit Smart CDN とは?
Smart CDN は、配信 URL を Transloadit の Assemblyに結び付けます。キャッシュミス時には、Transloadit がソースをインポートし、Template を実行して結果を配信します。後続のリクエストでは、派生ファイルが利用可能で、かつキャッシュ可能な間、キャッシュを再利用できます。
キャッシュ済みのレスポンスとキャッシュミスでは、コストとレイテンシーが異なります。ソースの場所、ファイル形式、プレビュー方式、キャッシュの有効期間、リクエストパターンがすべて影響します。当社が公開しているパフォーマンス測定値は、特定のテスト環境での結果であり、すべてのファイルのレイテンシーを保証するものではありません。
ファイルプレビュー機能とは?

この Robot は、ファイルのカテゴリごとに設定されたプレビュー方式を試します。たとえば、動画フレームを抽出する前に、埋め込まれたアートワークを探せます。より詳細なプレビューを生成できない場合は、アイコンを最終的なフォールバックにできます。対応形式、方式の適用順序、制限、パラメーターの正式な情報は、Robot リファレンスを参照してください。
主な機能
- 画像からリサイズ済みサムネイルを生成
- 動画にアートワーク、フレーム、その他の対応する動画プレビュー方式を使用
- 音声にアートワークまたは波形を使用
- ドキュメントにレンダリングしたページを使用
- Web ページにスクリーンショットを使用
- アーカイブや未対応のコンテンツに、フォールバック設定時はアイコンを使用
これらはプレビューであり、元のファイル全体を再現するものではありません。波形は音声プレーヤーではなく、サムネイルは動画のダウンロードではありません。実際に使用する形式でテストし、失敗時にも使えるフォールバックを用意してください。
ファイルプレビューの利点
オンデマンドでプレビューを生成すれば、誰も閲覧しないファイルの処理を省けます。キャッシュで重複処理を減らし、レスポンスを小さくすることで配信帯域幅を削減できます。すべてのファイルで公開前にプレビューが必要な場合や、初回閲覧時の処理待ちを許容できない場合は、事前処理が引き続き有効です。
削減効果はワークロードによって異なります。非常に小さな元画像よりプレビューが大きくなる場合もあるため、一定の削減率を想定するのではなく、配信バイト数を測定してください。
インタラクティブデモ
このデモでは、公開されている四つのサンプルファイルを使用します。フォームを送信したときだけプレビューを取得します。ファイルのアップロード、元の動画や音声のブラウザーへの取得、Assemblyのメタデータ検索は行いません。
公開デモは Transloadit の my-app Workspace 上で動作し、w、h、f、r、vs、v を受け取る既存の Template を使用します。以下の本番環境向けの例では、クエリフィールドとして size だけを受け取る、別の、より厳しく制限した Template を使用します。
デモの使い方
ソース、寸法、形式を選択します。リサイズ方式のオプションを選び、プレビューを生成を選択してください。キーボード操作でもタッチ操作でも、同じ送信操作を使います。表示される URL と測定値は、最後に送信した結果のものです。変更後に未送信の設定は反映されません。
実測の取得時間には、ブラウザーでプレビューの本文を受信する時間も含まれます。これは一度の観測値であり、条件を管理したコールドキャッシュやウォームキャッシュのベンチマークではありません。ブラウザーのキャッシュ、接続環境、処理のすべてが影響します。
配信量の比較は、それとは別の推計です。選択した単一の帯域幅単価とリクエスト数を両方のファイルに適用します。処理、ストレージ、リクエスト料金、サブスクリプション、税金、再試行は含みません。Transloadit と AWS の請求総額を比較するものではありません。また、元の動画をダウンロードすることと、静止画プレビューを表示することは同等ではありません。
プレビューはまだありません
配信の比較
見積もりでは、両方のファイルに同じ配信料金、20 ms の基準値、および 1 GB = 1,000,000,000 バイトを使用しています。処理、ストレージ、リクエスト料金、サブスクリプション、税金、再試行は含まれません。これは Transloadit の料金見積もりではありません。
導入方法
1. Transloadit への登録
2. Workspace の作成
例では、プレースホルダーの Workspace your-workspace を使用します。URL の作成時には、自分の Workspace に置き換えてください。公開デモの Workspace は、自分のアカウントとは別のものです。
3. Template の作成
preview という名前の Template を作成してください。この構成では、出力形式とリサイズ方式を意図的に固定し、サイズのフィールドを一つだけ受け取ります。my-website.com を、自分で管理する HTTPS オリジンに置き換えてください。以下で使用する二つのサンプルファイルをそこで公開するか、サーバーが管理するファイルマップを、自分の変更不可のオブジェクト名に変更してください。
{
"steps": {
"imported": {
"robot": "/http/import",
"url": "https://my-website.com/${fields.input}"
},
"previewed": {
"robot": "/file/preview",
"use": "imported",
"format": "png",
"width": "${fields.size}",
"height": "${fields.size}",
"resize_strategy": "fit",
"zoom": false
},
"served": {
"robot": "/file/serve",
"use": "previewed",
"cache_duration": 3600
}
}
}
以下の署名プログラムでは、三つのサイズと二つの既知の入力だけを許可します。Template 単体では、この許可リストは強制されません。Template API を通じて、require_signature_auth を 1 に設定し、steps の外側にある Template 属性として指定してください。公開前に、署名のないリクエストや改ざんされたリクエストが拒否されることを確認してください。任意のインポート URL や汎用の変換エンドポイントを公開しないでください。
4. Smart CDN の使用
この Template の署名なし URL は、次の構造です。
https://your-workspace.tlcdn.com/preview/photo-v1.jpg?size=320
パスは Workspace、Template、入力を識別します。入力は ${fields.input} になり、クエリは ${fields.size} に値を渡します。この構造例は、利用可能な認可トークンではありません。次のセクションのサーバー側プログラムが返す署名付き URL を使用してください。
ソースの内容を変更するときは、photo-v2.jpg のようにファイル名にバージョンを付けてください。同じ名前のオブジェクトを置き換えても、キャッシュ済みのすべての派生ファイルが即座に消えるわけではありません。
5. セキュリティ対策の実装
Workspace の Smart CDN が有効な Auth Keyと、そのAuth Secretを使用してください。後者は必ずサーバー上に保持します。環境変数は通常のシークレット管理プロセスで設定し、ブラウザー向けバンドルやコミットするファイルには含めないでください。
これは信頼できる運用担当者向けの CLI であり、HTTP 認証の実装ではありません。ネットワークリクエストを行わず、サーバーが管理する小規模な許可リストに署名します。Node.js 24 以降を使用し、公式 SDK をインストールしてください。
yarn add @transloadit/node@4.12.0
次の内容を sign-preview.mjs として保存してください。
import { Transloadit } from '@transloadit/node'
const inputs = new Map([
['photo', 'photo-v1.jpg'],
['audio', 'audio-v1.mp3'],
])
const sizes = new Set(['160', '320', '640'])
function main() {
const [name, size, ...extra] = process.argv.slice(2)
const input = inputs.get(name)
if (!input || !sizes.has(size) || extra.length !== 0) {
throw new Error('Expected one known file name and preview size')
}
const authKey = process.env.TRANSLOADIT_AUTH_KEY
const authSecret = process.env.TRANSLOADIT_AUTH_SECRET
const workspace = process.env.TRANSLOADIT_WORKSPACE
if (!authKey || !authSecret || !workspace || !/^[a-z0-9-]+$/.test(workspace)) {
throw new Error('Missing or invalid server configuration')
}
const client = new Transloadit({ authKey, authSecret })
const url = client.getSignedSmartCDNUrl({
workspace,
template: 'preview',
input,
urlParams: { size: Number(size) },
expiresAt: Date.now() + 60 * 60 * 1000,
})
process.stdout.write(url + '\n')
}
try {
main()
} catch {
console.error('Could not sign preview. Check the file, size, and server configuration.')
process.exitCode = 1
}
三つの環境変数を設定した状態で、次を実行してください。
node sign-preview.mjs photo 320
出力は Bearer URL です。取得した人は誰でも、有効期間中は使用できます。分析データ、エラーレポート、公開ログには含めないでください。この例では運用担当者向けに意図的に表示しますが、アプリケーションでは認可された要求者だけに渡してください。
アプリケーションのエンドポイントでは、まずユーザーを認証し、データベースでアセット識別子を解決して、その特定のアセットへのアクセス権を確認してから署名してください。許可するバリエーションと発行頻度に制限を設けてください。ファイル名を知っていることを認可の証明とみなさず、呼び出し元が指定するオリジン、Template、署名、有効期限を受け入れないでください。
SDK は署名と認証用クエリパラメーターを生成します。有効期限は UNIX エポックからのミリ秒数で表します。ここでは明示的に一時間に設定しています。実効的なキャッシュの有効期間も署名の残り有効期間に制限されるため、コンテンツの機密性とキャッシュの要件に応じて選んでください。現在の仕様は、署名とキャッシュの有効期間を参照してください。
6. 動作のカスタマイズ
パラメーターはサーバー側で検証してから、意図を持って追加してください。派生ファイルの数とコストを抑えるため、許可する組み合わせは少なく保ちます。リサイズ方式とプレビュー方式のリファレンスを参照してください。
機密性の高いコンテンツやユーザーが送信したコンテンツでは、インポート時のアクセス権、処理制限、プレビューから何が明らかになるかを確認してください。サムネイルや抽出したページにも、個人情報や非公開情報が含まれる場合があります。
既存ストレージの利用
非公開のクラウドストレージには、適切なインポート用 Robot と Template の認証情報を使用してください。ストレージの認証情報は、そのサーバー側設定に保持します。公開プレビューリンクに、バケットの認証情報や任意の署名付きソース URL を含めないでください。
既存 CDN の利用
既存の CDN を使うには、オリジン、キャッシュキー、署名、エラー処理を意図的に設定する必要があります。ワークロードに適した現在の連携方法については、お問い合わせください。署名付き URL の前段に別の CDN を置いても、アクセス制御や有効期限の意味が維持されるとは限りません。
事前処理
通常の Assembly で /file/preview を実行し、派生ファイルを自分のストレージへエクスポートすることもできます。アップロード時に処理することで、その後の利用可能性を予測しやすくする方式です。プレビューの準備が完了するまで公開を待つ必要がある場合や、静的 CDN で固定のファイル群を配信する場合に有効です。
現在の機能
この記事では、独立したロードマップの更新はすでに終了しています。現在の出力形式と方式は、Robot リファレンスで確認してください。記事の初公開時に実験段階だった機能も含まれます。
料金
処理と配信は、ワークロードの別々の構成要素です。実際の Template、ファイルサイズ、リクエスト数、キャッシュの動作、現在の料金に基づいて見積もってください。アカウントの上限と出力制限はプランによって異なります。デモで調整できる帯域幅単価は仮定値であり、Transloadit が提示する料金ではありません。
デモ相談
ファイルの種類、想定トラフィック、プライバシー要件、既存のストレージについて、チームにご相談ください。
まとめ
代表的な少数のファイルと、制限を設けたプレビュー用 Template から始めてください。返された画像を確認し、実際のレスポンスサイズを測定して、失敗時やキャッシュミス時の動作をテストし、署名付きアクセスを検証してください。ワークフローとそのコストがアプリケーションに適していると確認できたら、許可するバリエーションを増やしてください。
