On-Demand-Medienvorschauen mit Smart CDN

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Ein Dateibrowser muss selten ein ganzes Video herunterladen, nur um zu zeigen, was es enthält. Ein Thumbnail, eine Audio-Wellenform oder ein Dateityp-Symbol kann diesen Kontext mit einer weit kleineren Antwort liefern.

Der Robot /file/preview EN (English) erzeugt diese Vorschauen. Smart CDN kann den Verarbeitungs-Workflow ausführen, sobald eine Vorschau angefordert wird, und das Ergebnis zwischenspeichern. Dieser Artikel verbindet eine funktionierende Demo, ein eng begrenztes Template und serverseitiges Signieren von URLs.

Was ist das Transloadit Smart CDN?

Smart CDN verbindet eine Auslieferungs-URL mit einer Assembly von Transloadit. Bei einem Cache-Miss importiert Transloadit die Quelle, führt das Template aus und liefert das Ergebnis aus. Eine spätere Anfrage kann ein zwischengespeichertes Derivat wiederverwenden, solange es verfügbar und cachefähig bleibt.

Eine warme Antwort und ein Cache-Miss verursachen unterschiedliche Kosten und Latenzen. Speicherort der Quelle, Dateiformat, Vorschau-Strategie, Cache-Lebensdauer und Anfragemuster spielen alle eine Rolle. Unsere veröffentlichten Performance-Messungen beschreiben einen bestimmten Testaufbau, keine Latenzgarantie für jede Datei.

Was ist die Dateivorschau-Funktion?

Der Robot probiert die konfigurierten Vorschau-Strategien für jede Dateikategorie durch. Zum Beispiel kann er nach einem eingebetteten Coverbild suchen, bevor er ein Videobild extrahiert. Ein Symbol kann der letzte Fallback sein, wenn keine reichhaltigere Vorschau verfügbar ist. Die Robot-Referenz EN (English) ist die maßgebliche Quelle für unterstützte Formate, Reihenfolge der Strategien, Limits und Parameter.

Wichtige Funktionen

• Bilder können zu Thumbnails mit angepasster Größe werden.
• Videos können ein Coverbild, ein Einzelbild oder andere unterstützte Video-Strategien nutzen.
• Audio kann ein Coverbild oder eine Wellenform nutzen.
• Dokumente können eine gerenderte Seite nutzen.
• Webseiten können einen Screenshot nutzen.
• Archive und nicht unterstützte Inhalte können ein Symbol nutzen, wenn dieser Fallback konfiguriert ist.

Dies sind Vorschauen, keine vollständigen Varianten des Originals. Eine Wellenform ist kein Audioplayer, und ein Thumbnail ist kein Video-Download. Testen Sie Ihre eigenen Formate und halten Sie einen brauchbaren Fallback für Fehlerfälle bereit.

Vorteile von Dateivorschauen

Vorschauen bei Bedarf zu erzeugen, kann Arbeit für Dateien vermeiden, die niemand ansieht. Caching kann wiederholte Verarbeitung reduzieren, und kleinere Antworten können die Bandbreite der Auslieferung senken. Vorverarbeitung bleibt sinnvoll, wenn jede Datei vor der Veröffentlichung eine Vorschau benötigt oder wenn eine Verarbeitungsverzögerung beim ersten Aufruf nicht akzeptabel ist.

Die Einsparungen hängen von der Arbeitslast ab. Eine Vorschau kann sogar größer sein als ein winziges Quellbild. Messen Sie deshalb die ausgelieferten Bytes, statt einen festen Prozentsatz an Reduktion anzunehmen.

Interaktive Demo

Die Demo verwendet vier öffentliche Beispieldateien. Sie ruft eine Vorschau erst ab, wenn Sie das Formular absenden. Sie lädt Ihre Dateien nicht hoch, holt weder das Original-Video noch die Original-Audiodatei in Ihren Browser und führt keine Metadaten-Abfrage für eine Assembly aus.

Die öffentliche Demo läuft im Workspace my-app von Transloadit mit einem bestehenden Template, das w, h, f, r, vs und v akzeptiert. Das Produktionsbeispiel weiter unten verwendet ein separates, stärker eingeschränktes Template, das nur size als Abfragefeld akzeptiert.

So nutzen Sie die Demo

Wählen Sie Quelle, Abmessungen und Format. Legen Sie die Option Strategie zur Größenänderung fest und wählen Sie dann Vorschau erzeugen. Änderungen per Tastatur und Touch nutzen dieselbe Absende-Aktion. Die angezeigte URL und die Messwerte gehören zum zuletzt abgesendeten Ergebnis, nicht zu Einstellungen, die Sie geändert, aber nicht abgesendet haben.

Die gemessene Abrufzeit umfasst den Empfang des Vorschau-Inhalts in Ihrem Browser. Sie ist eine einzelne Beobachtung, kein kontrollierter Benchmark mit kaltem oder warmem Cache. Browser-Caching, Ihre Verbindung und die Verarbeitung können sie alle beeinflussen.

Der Auslieferungsvergleich ist eine separate Schätzung: Er wendet einen gewählten Bandbreitenpreis und eine Anzahl von Anfragen auf beide Dateien an. Verarbeitung, Storage, Anfragegebühren, Abonnements, Steuern und Retries sind ausgenommen. Es ist kein Vergleich vollständiger Rechnungen von Transloadit und AWS. Das Herunterladen eines Original-Videos entspricht zudem nicht der Anzeige einer Standbild-Vorschau.

Erste Schritte

1. Bei Transloadit registrieren

Erstellen Sie ein Konto und sehen Sie sich die aktuellen Tarife und Limits an.

2. Workspace erstellen

In den Beispielen dient der Workspace your-workspace als Platzhalter. Ersetzen Sie ihn beim Erstellen von URLs durch Ihren eigenen Workspace. Der öffentliche Demo-Workspace ist von Ihrem Konto getrennt.

3. Template erstellen

Erstellen Sie ein Template mit dem Namen preview. Diese Version legt Ausgabeformat und Strategie zur Größenänderung bewusst fest und akzeptiert nur ein Größenfeld. Ersetzen Sie my-website.com durch einen HTTPS-Origin, den Sie kontrollieren. Veröffentlichen Sie dort die beiden unten verwendeten Beispieldateien, oder ändern Sie die serverseitige Dateizuordnung auf Ihre eigenen unveränderlichen Objektnamen.

{
  "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
    }
  }
}

Das Signierprogramm unten erlaubt nur drei Größen und zwei bekannte Eingaben. Das Template allein erzwingt diese Allowlist nicht. Setzen Sie require_signature_auth auf 1, und zwar über die Template API, als Template-Attribut außerhalb von steps. Prüfen Sie vor der Veröffentlichung, dass unsignierte und manipulierte Anfragen abgelehnt werden. Geben Sie keine beliebige Import-URL und keinen universellen Transformations-Endpunkt preis.

4. Smart CDN nutzen

Die unsignierte URL-Struktur für dieses Template lautet:

https://your-workspace.tlcdn.com/preview/photo-v1.jpg?size=320

Der Pfad identifiziert Workspace, Template und Eingabe. Die Eingabe wird zu ${fields.input}, und die Abfrage liefert ${fields.size}. Dieses strukturelle Beispiel ist kein nutzbares Autorisierungs-Token. Verwenden Sie die signierte URL, die das serverseitige Programm im nächsten Abschnitt zurückgibt.

Versionieren Sie Quelldateinamen, wenn sich deren Inhalt ändert, etwa photo-v2.jpg. Wenn Sie ein Objekt unter demselben Namen ersetzen, verschwindet nicht sofort jedes zwischengespeicherte Derivat.

5. Sicherheitsmaßnahmen umsetzen

Verwenden Sie den für Smart CDN freigeschalteten Auth Key aus Ihrem Workspace und das zugehörige Auth Secret. Letzteres muss auf dem Server bleiben. Konfigurieren Sie Umgebungsvariablen über Ihren üblichen Prozess zum Verwalten von Secrets, nicht über ein Browser-Bundle oder eine eingecheckte Datei.

Dies ist ein CLI für vertrauenswürdige Betreiber, keine Implementierung einer HTTP-Authentifizierung. Es signiert eine kleine serverseitige Allowlist, ohne eine Netzwerkanfrage zu stellen. Verwenden Sie Node.js 24 oder neuer und installieren Sie das offizielle SDK:

yarn add @transloadit/node@4.12.0

Speichern Sie dies als 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
}

Wenn diese drei Umgebungsvariablen konfiguriert sind, führen Sie aus:

node sign-preview.mjs photo 320

Die Ausgabe ist eine URL nach dem Bearer-Prinzip: Wer sie erhält, kann sie während ihrer Gültigkeitsdauer verwenden. Verwenden Sie sie nicht in Analytics, Fehlerberichten oder öffentlichen Logs. Dieses Beispiel gibt sie absichtlich für den Betreiber aus; eine Anwendung sollte sie nur an die autorisierte anfragende Stelle ausliefern.

Authentifizieren Sie bei einem Anwendungs-Endpunkt zuerst die Nutzerin oder den Nutzer, lösen Sie eine Asset-Kennung über Ihre Datenbank auf und prüfen Sie den Zugriff auf genau dieses Asset, bevor Sie signieren. Begrenzen Sie die erlaubten Varianten und die Ausstellungsraten. Betrachten Sie die Kenntnis eines Dateinamens nicht als Autorisierungsnachweis, und akzeptieren Sie keine vom Aufrufer bereitgestellten Origins, Templates, Signaturen oder Ablaufzeiten.

Das SDK erzeugt die Signatur und die Authentifizierungs-Abfrageparameter. Das Ablaufdatum wird in Millisekunden seit der UNIX-Epoche angegeben. Hier ist es explizit auf eine Stunde gesetzt. Die effektive Cache-Lebensdauer wird zusätzlich durch die verbleibende Gültigkeit der Signatur begrenzt; wählen Sie sie passend zur Sensibilität der Inhalte und zu Ihren Caching-Anforderungen. Siehe Signierung und Cache-Lebensdauer für die aktuell geltenden Regeln.

6. Verhalten anpassen

Fügen Sie Parameter bewusst hinzu, nachdem Sie sie auf Ihrem Server validiert haben. Halten Sie die erlaubten Kombinationen klein, um Anzahl und Kosten der Derivate zu begrenzen. Siehe Strategien zur Größenänderung und die Referenz der Vorschau-Strategien EN (English).

Prüfen Sie bei sensiblen oder von Nutzenden eingereichten Inhalten den Importzugriff, die Verarbeitungslimits und das, was eine Vorschau offenlegen kann. Auch ein Thumbnail oder eine extrahierte Seite kann private Informationen enthalten.

Eigenen Storage einbinden

Verwenden Sie für privaten Cloud-Storage den passenden Import-Robot und die passenden Template-Zugangsdaten. Bewahren Sie die Zugangsdaten für den Storage in dieser serverseitigen Konfiguration auf. Nehmen Sie keine Bucket-Zugangsdaten und keine beliebige vorsignierte Quell-URL in einen öffentlichen Vorschau-Link auf.

Eigenes CDN einbinden

Ein bestehendes CDN erfordert eine bewusste Konfiguration von Origin, Cache-Key, Signierung und Fehlerbehandlung. Kontaktieren Sie uns zu den aktuellen Integrationsmöglichkeiten für Ihre Arbeitslast. Gehen Sie nicht davon aus, dass ein weiteres CDN vor einer signierten URL deren Zugriffskontroll- oder Ablaufsemantik erhält.

Vorverarbeitung

Sie können /file/preview auch in einer regulären Assembly ausführen und die Derivate in Ihren eigenen Storage exportieren. Das tauscht Arbeit beim Upload gegen vorhersehbare Verfügbarkeit später ein. Das ist nützlich, wenn die Veröffentlichung warten muss, bis die Vorschauen bereit sind, oder wenn ein statisches CDN eine feste Menge an Dateien ausliefern soll.

Aktuelle Funktionen

Dieser Artikel pflegt keine separate Roadmap mehr. Aktuelle Ausgabeformate und Strategien finden Sie in der Robot-Referenz EN (English), einschließlich Funktionen, die zur Erstveröffentlichung dieses Beitrags noch experimentell waren.

Preise

Verarbeitung und Auslieferung sind unterschiedliche Teile der Arbeitslast. Schätzen Sie sie anhand Ihrer tatsächlichen Templates, Dateigrößen, Anfragezahlen, Ihres Cache-Verhaltens und der aktuellen Preise. Kontolimits und Ausgabebeschränkungen unterscheiden sich je nach Tarif. Die anpassbare Bandbreitenrate in der Demo ist eine Annahme, kein angebotener Transloadit-Preis.

Demo-Gespräch

Sprechen Sie mit unserem Team über Ihre Dateitypen, den erwarteten Traffic, Ihre Datenschutzanforderungen und Ihren vorhandenen Storage.

Fazit

Beginnen Sie mit einigen repräsentativen Dateien und einem eng begrenzten Vorschau-Template. Prüfen Sie die zurückgegebenen Bilder, messen Sie die tatsächlichen Antwortgrößen, testen Sie Fehlerfälle und Cache-Misses und überprüfen Sie den signierten Zugriff. Erweitern Sie die erlaubten Varianten, sobald der Workflow und seine Kosten für Ihre Anwendung sinnvoll sind.