Datei-Uploads, Bildoptimierung, Video-Encoding und Ihr eigener S3-Bucket

Arbeiten zum Upload-Zeitpunkt von Arbeiten zum Anfragezeitpunkt trennen

Beginnen Sie mit zwei Wegen statt einer vagen „Optimierungspipeline“. Auf dem Upload-Zeitpfad sendet ein Browser eine Datei über Uppy und tus an eine Transloadit-Assembly. Das gespeicherte Template validiert die eingegangene Datei, erstellt alle Ausgaben, die sofort existieren müssen, und exportiert ausgewählte Dateien nach S3. Die Anwendung speichert die Assembly-ID und die dauerhafte S3-Objektidentität mit ihrem Asset-Datensatz.

Auf dem Anfrage-Zeitpfad fordert ein Browser eine Smart-CDN-URL an. Die URL identifiziert ein gespeichertes Template und einen Eingabepfad in S3. Bei einem Cache-Miss importiert Transloadit dieses Objekt, wendet das Template mit den zulässigen Assembly Variables an und liefert ein Ergebnis über /file/serve aus. Die Auslieferungsschicht cacht die Antwort; eine erneute Anfrage kann das Derivat wiederverwenden, ohne die Transformation erneut auszuführen.

Eine hochgeladene Datei ohne Transformation in S3 speichern

Verwenden Sie ein Upload-only-Template, wenn Transloadit die akzeptierte Datei entgegennehmen und exportieren soll, ohne ihre Medien-Bytes zu ändern. /upload/handle nimmt die Eingabe entgegen, und /s3/store wählt :original. Der Zielpfad nutzt Assembly Variables, damit sich gleichzeitige Uploads nicht gegenseitig überschreiben, während der ursprüngliche, URL-sichere Dateiname erkennbar bleibt.

Das Beispiel verweist auf Template-Zugangsdaten und setzt acl: "private", da /s3/store standardmäßig public-read verwendet. Setzen Sie bucket_region auf die tatsächliche AWS-Region des Buckets, um einen GetBucketLocation-Lookup zu vermeiden, und entfernen Sie s3:GetBucketLocation aus der IAM-Richtlinie dieser Zugangsdaten. Behandeln Sie ein öffentliches Objekt als ausdrückliche Produktentscheidung, und prüfen Sie den tatsächlichen S3-Zugriff getrennt von der Einstellung des Robots.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "stored": {
      "use": ":original",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "uploads/${unique_prefix}/${file.url_name}"
    }
  }
}

Den Upload empfangen, validieren, optimieren und exportieren

Verwenden Sie ein gespeichertes Bild-Template, um zu begrenzen, was Browsercode anfordern darf. /upload/handle nimmt die Datei entgegen, /file/filter kann Dateien ablehnen, deren erkannte Eigenschaften der Richtlinie nicht entsprechen, /image/resize erstellt ein festes WebP-Derivat, und /image/optimize verkleinert diese Ausgabe. /s3/store exportiert dann genau die Steps, die sein use-Wert benennt. Richten Sie es nur auf optimized, um das Derivat zu speichern, nur auf accepted_images, um das akzeptierte Original zu speichern, oder auf beide, um beide Objekte zu behalten. preserve_meta_data bleibt bewusst auf seinem Standardwert true, um Bildmetadaten wie Urheberrechtsangaben des Fotografen zu erhalten, auch wenn dies unter der Priorität compression-ratio eine geringfügige Größenzunahme bedeutet.

Uppy ist die Upload-Ebene im Browser, nicht die Autorisierungsgrenze. Lassen Sie das Transloadit-Plugin kurzlebige, signierte Assembly-Parameter vom Anwendungsserver anfordern. Lassen Sie allow_steps_override deaktiviert, wenn der Browser die gespeicherten Steps nicht ersetzen oder ein anderes Ziel auswählen darf. Verwenden Sie erneut die private ACL und die tatsächliche AWS-Bucket-Region aus dem Nur-Upload-Beispiel. Sowohl ${file.id} als auch ${unique_prefix} sind für jede exportierte Datei eindeutig; dieses Bildbeispiel verwendet die schrägstrichfreie ${file.id}, sodass das mittlere Pfadsegment aus einer einzigen Komponente besteht, was vorhersehbare Schlüssel images/${file.id}/${file.url_name} ergibt, die Smart CDN referenzieren kann, während die Upload- und Videobeispiele ${unique_prefix} als kollisionsvermeidendes Verzeichnis verwenden. Da ${file.id} für jede exportierte Datei eindeutig ist, lösen accepted_images und optimized zu unterschiedlichen Schlüsseln unter images/ auf; die gemeinsame Pfadvorlage überschreibt nichts, daher sollten Sie jeden exportierten Schlüssel separat im Anwendungszustand erfassen. Betrachten Sie den Upload für das Produkt erst als abgeschlossen, nachdem die Anwendung das Assembly-Ergebnis und die dauerhaften S3-Schlüssel abgeglichen hat.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^(image/jpeg|image/png|image/gif|image/webp|image/avif)$"]],
      "error_on_decline": true
    },
    "resized": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600,
      "format": "webp"
    },
    "optimized": {
      "use": "resized",
      "robot": "/image/optimize",
      "priority": "compression-ratio",
      "preserve_meta_data": true
    },
    "stored": {
      "use": ["accepted_images", "optimized"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "images/${file.id}/${file.url_name}"
    }
  }
}

Ein Video vor der Speicherung in S3 codieren

Verwenden Sie ein Video-only-Template, wenn das dauerhafte S3-Objekt eine Variante für die Wiedergabe statt der hochgeladenen Quelle sein soll. /video/encode liest :original und wendet eine getestete Voreinstellung an. web/mp4/720p ist ein konkreter Ausgangspunkt mit 1280×720 als MP4, keine universelle Empfehlung; validieren Sie Quellabmessungen, Bildrate, Audio, Untertitel, Qualität, Geräteunterstützung, Verarbeitungszeit und Kosten für den Wiedergabevertrag des Produkts. Begrenzen Sie zudem die Anfragerate für diesen Endpunkt unabhängig vom Upload-Datenverkehr.

Das Beispiel exportiert den encoded-Step und lässt die Quelle bei diesem Speichervorgang aus. Fügen Sie einen zweiten /s3/store-Step hinzu, wenn die Quelle für ein erneutes Encoding in höherer Qualität, Audits oder Migration verfügbar bleiben muss. Encoding kann eine Anwendungsanfrage überdauern, gleichen Sie daher den Assembly Status oder einen verifizierten Abschluss-Callback ab, bevor Sie den S3-Schlüssel als veröffentlichbar behandeln.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/720p"
    },
    "stored": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "videos/${unique_prefix}/${file.url_name}"
    }
  }
}

Ein S3-Original bei Bedarf über Smart CDN transformieren

Eine Smart-CDN-Integration beginnt weiterhin mit einem gespeicherten Template. /s3/import löst den Eingabepfad mithilfe eingeschränkter Template-Zugangsdaten auf, /image/resize liest den per URL übergebenen Wert ${fields.w} und den anhand der Anfrage ausgehandelten Wert ${browser.wanted_image_format}, und /file/serve wählt die Antwort aus. Auf diesem Pfad leitet die Smart-CDN-Edge von Transloadit einen vertrauenswürdigen, vornormalisierten x-tl-image-format-Header aus dem Accept-Header des Clients ab. Der Header wird serverseitig geschrieben und ist nicht clientseitig steuerbar; Entwickler verweisen in den Instructions nur auf ${browser.wanted_image_format}, was zum selben Wert avif, webp oder jpg aufgelöst wird.

Eine URL wie https://my-workspace.tlcdn.com/responsive-image/images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg?w=640 übergibt images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg als impliziten Wert ${fields.input} – den Pfad nach dem Template-Namen, ohne führenden Schrägstrich – und 640 als ${fields.w}. Diese Eingabe entspricht dem gespeicherten Schlüssel images/${file.id}/${file.url_name} für das dauerhafte accepted_images-Original, den /s3/import für die On-Demand-Größenänderung liest. Das optimierte Derivat ist ein separates Objekt unter einem eigenen ${file.id}-Präfix. Da sich die beiden Ausgaben kein Verzeichnis teilen, speichern Sie jeden exportierten Schlüssel im Anwendungszustand, statt einen Schlüssel aus dem anderen oder aus der Anfrage-URL abzuleiten.

Behalten Sie das vollständige Präfix images/ in der Smart-CDN-URL bei; fügen Sie es nicht erneut im Template hinzu. Smart-CDN-Abfragewerte kommen als Zeichenketten an, daher wird die Breite mit den String-Literalen "320" und "640" aus der Positivliste der Breiten verglichen; eine nicht übereinstimmende Breite fällt auf 1280 zurück. Wenn Sie die Pfadzuordnung und die Positivliste für Transformationen getrennt halten, lässt sich leichter prüfen, welches S3-Objekt gelesen werden kann und welche Variante angefordert werden kann.

Interpolieren Sie keinen uneingeschränkten Pfad, keine uneingeschränkte Breite, keine uneingeschränkte Qualität und kein uneingeschränktes Format, nur weil dies als Feld eintreffen kann. Beschränken Sie die S3-Zugangsdaten auf ein vorgesehenes Präfix, lassen Sie die vertrauenswürdige Anwendung den exportierten Schlüssel in ihrem Asset-Datensatz nachschlagen und signieren Sie eine URL, die genau diesen Schlüssel enthält. Der Anfrage-Zeitpfad wählt dieses gespeicherte Template über seine Smart-CDN-URL aus, statt vom Browser übermittelte Assembly Instructions zu akzeptieren; deshalb verwendet dieses Beispiel nicht die Upload-Zeit-Einstellung allow_steps_override. Verwenden Sie wie im reinen Upload-Beispiel die tatsächliche AWS-Bucket-Region. Validieren oder mappen Sie Transformationswerte im Template. Einfache Lookups wie ${fields.input} sind kostenlos, während Vergleiche, Arithmetik und Ternäre komplexe Dynamic Evaluation sind: Die Breiten- und Format-Ternäre in diesem Beispiel rufen /script/run auf und werden bei jedem Cache-Miss abgerechnet. Der Format-Ausdruck bildet den jpg-Fallback auf null ab, sodass Anfragen ohne Präferenz für ein modernes Format das Originalformat beibehalten, statt Transparenz oder Animation durch unnötiges erneutes Encoding zu verlieren. Siehe den Eintrag ${browser.wanted_image_format} in der Referenz zu Assembly Variables. Messen Sie die erste ungecachte Transformation getrennt von der anschließenden gecachten Auslieferung.

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "path": "${fields.input}"
    },
    "resized": {
      "use": "imported",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": "${fields.w === '320' ? 320 : fields.w === '640' ? 640 : 1280}",
      "format": "${browser.wanted_image_format === 'jpg' ? null : browser.wanted_image_format}"
    },
    "served": {
      "use": "resized",
      "robot": "/file/serve",
      "cache_duration": 604800
    }
  }
}

Entscheiden, was dauerhaft gespeichert und was bei Bedarf erzeugt wird

Ein Original in S3 vorzuhalten, bietet eine stabile Quelle für die erneute Verarbeitung, macht es aber nicht erforderlich, jede responsive Variante zu speichern. Exportieren Sie kanonische Ausgaben, die das Produkt unabhängig von einem Cache benötigt: einen freigegebenen Master, ein Marktplatz-Listingbild, ein Druck-Asset oder ein unveränderliches Release-Derivat. Lassen Sie Smart CDN begrenzte Präsentationsvarianten erstellen, deren Abmessungen vom anfragenden Gerät oder Layout abhängen.

Umgekehrt sollten Sie sich nicht nur auf einen On-Demand-Pfad verlassen, wenn die erste Anfrage keine Verarbeitungslatenz tolerieren kann, ein Redakteur die exakten Pixel freigeben muss oder nachgelagerte Systeme vor der Veröffentlichung ein dauerhaftes Objekt benötigen. In diesem Fall erstellen und exportieren Sie das Derivat in der Assembly zum Zeitpunkt des Uploads. Dieselbe Anwendung kann beide Ansätze für unterschiedliche Ausgabeklassen nutzen, ohne den dauerhaften Eigentümer der Quelle zu ändern.

Dies fair mit einer nativen AWS-Pipeline vergleichen

Erstellen Sie separate Template-Zugangsdaten mit minimalen Berechtigungen, wenn Upload-Exporte und Smart-CDN-Importe unterschiedliche AWS-Aktionen oder -Präfixe benötigen. Halten Sie rohe AWS-Schlüssel, das Auth Secret von Transloadit und uneingeschränkte Instructions aus Browser-Bundles heraus. Der Anwendungsserver sollte den Nutzer autorisieren, das Template auswählen und nur die kurzlebigen Upload-Parameter oder die signierte Smart-CDN-URL ausstellen, die für dieses Asset geeignet sind.

Ein erfolgreicher Upload oder eine gültige Signatur ist keine Freigabe zur Veröffentlichung. Validieren Sie den erkannten MIME-Typ und die Größe in der Assembly, verknüpfen Sie Callbacks idempotent mit dem erwarteten Mandanten und der Assembly, und geben Sie ein Ergebnis erst frei, wenn das dauerhafte Objekt und der Anwendungsdatensatz übereinstimmen. Planen Sie für Smart CDN Quellversionierung, URL-Ablauf, Cache-Lebensdauer und Löschung gemeinsam, damit das Ersetzen eines S3-Schlüssels keine unbeabsichtigte Derivat-Adresse aktiv lässt.

Die Anwendung, den Bucket und die Transformationsoberfläche schützen

Ein nativer Aufbau kann über eine vorsignierte S3-URL hochladen, auf object-created-Ereignisse reagieren, mit Lambda oder einem anderen Rechendienst verarbeiten, Derivate speichern und sie über ein CDN ausliefern. Das kann gut passen, wenn die Last innerhalb der unterstützten Laufzeitgrenzen bleibt und das Team Autorisierung, Wiederholungsversuche, Warteschlangen, Codecs, Nebenläufigkeit, Beobachtbarkeit und Fehlerbehebung selbst betreiben möchte.

Vergleichen Sie vollständige Produktionspfade und nicht nur eine erfolgreiche Größenänderung. Testen Sie unterbrochene Uploads, große Quelldateien, fehlerhafte Bilder, Ausrichtung und Farbe, doppelte Ereignisse, unvollständige Exporte, Nebenläufigkeitsspitzen, kalte Transformationen, Cache-Invalidierung, regionale Latenz und Löschung. Berücksichtigen Sie Entwicklungs- und Betriebsaufwand zusätzlich zu den Kosten für Upload, Verarbeitung, Speicher, Anfragen und Egress. Die entscheidende Wahl ist, welche betrieblichen Verantwortlichkeiten das Team selbst übernehmen möchte.