Wichtigste Erkenntnisse
- Verwenden Sie
/upload/handlegefolgt von/tus/store, um eine unveränderte hochgeladene Datei an einen tus-kompatiblen Endpunkt weiterzuleiten. - Führen Sie
/image/optimizevor/tus/storeaus, wenn das empfangende System ein optimiertes Bild erhalten soll. - Führen Sie
/video/encodemit einer getesteten Voreinstellung vor/tus/storeaus, wenn das Ziel eine Wiedergabevariante erhalten soll.
tus ist ein fortsetzbares Upload-Protokoll, kein Objektspeicherprodukt. In diesen Workflows lädt ein Client zunächst zu einer Transloadit-Assembly hoch, optionale Bild- oder Video-Steps erzeugen die gewünschte Ausgabe, und /tus/store startet einen separaten ausgehenden tus-Upload zum konfigurierten Ziel-Endpunkt. Diese Unterscheidung ist wichtig für Zugangsdaten, Wiederholungen, Ergebnis-URLs und den Abgleich in der Anwendung.
Worauf es besonders ankommt
- Speichern Sie Autorisierungs-Header für das Ziel in HTTP-Template-Zugangsdaten statt in browserseitig sichtbaren Instructions.
- Gleichen Sie die Assembly und die empfangende Anwendung ab, bevor Sie ein Asset im Produktzustand als bereit markieren.
tus als Auslieferungsgrenze modellieren
Ein Transloadit-Upload und ein /tus/store-Export sind zwei getrennte Übertragungen. Die erste bringt Client-Bytes in eine Assembly. Die Assembly kann die Datei unverändert lassen oder ein Bild- oder Video-Derivat erzeugen. Die zweite Übertragung sendet das ausgewählte Ergebnis von Transloadit an Ihren tus-Endpunkt. Diese Architektur ist nützlich, wenn die empfangende Plattform bereits tus bereitstellt, Sie aber dennoch verwaltete Verarbeitung vor der Auslieferung wünschen.
Das Ziel ist für alles nach Protokollabschluss verantwortlich. Dessen Anwendung entscheidet, ob der Upload in dauerhaften Speicher verschoben, ein Asset-Datensatz erstellt, er gescannt, veröffentlicht oder später abgelehnt wird. Erfassen Sie sowohl die Assembly-ID als auch die stabile Kennung des Empfängers. Gehen Sie nicht davon aus, dass die tus-Upload-URL ein dauerhafter Objektbezeichner oder eine lesbare Auslieferungs-URL ist, sofern der Empfänger diesen Vertrag nicht ausdrücklich zusichert.
Eingehende Übertragung
Client → Transloadit-Assembly, über die vom SDK oder der Integration ausgewählte Upload-Methode.
Ausgehende Übertragung
Assembly-Ergebnis → /tus/store → der konfigurierte tus-kompatible Ziel-Endpunkt.
Dauerhaftigkeitsgrenze
Persistenz und Veröffentlichung auf Empfängerseite liegen außerhalb des tus-Protokolls und des Transloadit-Workflows.
Eine hochgeladene Datei ohne Transformation weiterleiten
Verwenden Sie das reine Upload-Template, wenn das Ziel die von der Assembly akzeptierte Originaldatei erhalten soll. /upload/handle stellt diese Eingabe als :original bereit, und /tus/store wählt sie über use aus. Der erforderliche endpoint muss die Ziel-URL sein, die tus-Uploads erstellt, nicht die URL eines bestehenden Objekts oder einer Browser-Download-Seite.
Das Beispiel referenziert HTTP-Template-Zugangsdaten für statische Ziel-Header. Lassen Sie allow_steps_override auf false, wenn Clients den Endpunkt nicht ersetzen, die Authentifizierung nicht entfernen oder eine Datei nicht umleiten dürfen. Wenn der Empfänger Mandanten- oder Asset-Kontext benötigt, bevorzugen Sie nicht-geheime Metadaten mit einem serverseitig autorisierten Endpunkt oder eingeschränkten Zugangsdaten und validieren Sie diesen Kontext auf der Empfängerseite erneut.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"delivered": {
"use": ":original",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Ein Bild vor der tus-Auslieferung optimieren
Verbinden Sie für einen reinen Bildvertrag /image/optimize mit :original und liefern Sie den optimized Step aus. Das Beispiel erhält Metadaten und nutzt verlustfreie PNG-Optimierung (lossy: false); dieses Flag wirkt sich nicht auf die Optimierung von JPEG, GIF, WebP oder SVG aus. Prüfen Sie vor einer Änderung dieser Einstellungen, ob das Entfernen von Metadaten oder verlustbehaftete PNG-Optimierung angemessen ist, da beides Informationen verändern kann, die die empfangende Anwendung erwartet. Die vom Standardwert abweichende priority: "compression-ratio" im Beispiel bevorzugt eine kleinere Ausgabedatei gegenüber der Verarbeitungsgeschwindigkeit; conversion-speed, der Standardwert, geht den umgekehrten Kompromiss ein.
Dieses Rezept ändert weder die Größe noch das Format. Fügen Sie /image/resize vor der Optimierung hinzu, wenn der Empfänger feste Abmessungen oder ein bestimmtes Format benötigt. Speichern oder liefern Sie das Original separat aus, wenn Wiederherstellung und künftige Weiterverarbeitung wichtig sind. Ein nicht unterstützter Bildtyp kann /image/optimize unverändert durchlaufen, verwenden Sie daher eine explizite Validierung, wenn der Empfänger ein eingeschränktes Format benötigt.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"optimized": {
"use": ":original",
"robot": "/image/optimize",
"priority": "compression-ratio",
"preserve_meta_data": true,
"lossy": false
},
"delivered": {
"use": "optimized",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Ein Video vor der tus-Auslieferung codieren
Verbinden Sie für einen reinen Videovertrag /video/encode mit dem Upload und übergeben Sie /tus/store diesen Step mit dem codierten Ergebnis. web/mp4/720p ist ein konkreter, auflösungsspezifischer MP4-Ausgangspunkt, keine universelle Empfehlung für eine Voreinstellung. Testen Sie Quellabmessungen, Bildrate, Audio, Untertitel, Wiedergabekompatibilität, Verarbeitungszeit und Kosten gegen die tatsächlichen Anforderungen des Empfängers.
Sowohl das Video-Encoding als auch die ausgehende tus-Übertragung können eine Anwendungsanfrage überdauern. Nutzen Sie den Assembly Status oder einen verifizierten Abschluss-Callback und prüfen Sie anschließend den eigenen Abschlussstatus der empfangenden Anwendung. Speichern oder leiten Sie die Quelle separat weiter, wenn sie für ein höherwertiges erneutes Encoding, ein Audit, eine Wiederherstellung oder eine Migration benötigt wird.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"encoded": {
"use": ":original",
"robot": "/video/encode",
"preset": "web/mp4/720p"
},
"delivered": {
"use": "encoded",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Header, Metadaten und gemeldete URLs bewusst wählen
Verwenden Sie HTTP-Template-Zugangsdaten für statische Autorisierungsheader. Der Robot akzeptiert auch dynamische headers, aber das Signieren von Instructions garantiert nur deren Integrität, niemals deren Vertraulichkeit: Ein Browser kann alles lesen, was er übermittelt. Dynamische Geheimnisse dürfen daher niemals in browser-sichtbaren Instructions erscheinen. Bewahren Sie sie in Template-Zugangsdaten auf, oder übermitteln Sie die Assembly Server-zu-Server, sodass die Werte den Browser nie erreichen. Die Zielmetadaten sind eine separate Map: Der Robot ersetzt die vom Aufrufer übergebenen Werte für filename, basename und extension durch Informationen aus der verarbeiteten Datei, während andere Schlüssel unverändert wie angegeben durchgereicht werden. Halten Sie die Metadaten klein, geheimnisfrei und an den Feldern ausgerichtet, die der Empfänger tatsächlich validiert, anstatt sie als Autorisierung zu behandeln.
Ohne url_template meldet der Robot die vom Ziel zurückgegebene Upload-URL. Eine weggelassene ssl_url_template kann diese URL nur dann wiederverwenden, wenn sie mit HTTPS beginnt. URL-Vorlagen ändern die Darstellung des Ergebnisses; sie ändern nicht die Berechtigungen des Empfängers, wandeln eine Upload-URL nicht in einen Download-Endpunkt um und garantieren keine langfristige Stabilität. Erfassen Sie die kanonische Asset-ID des Empfängers, nachdem dieser den Upload verarbeitet hat.
Wiederholungsversuche testen und beide Systeme abgleichen
Testen Sie abgelaufene Autorisierung, Ablehnung durch den Endpunkt, unterbrochene Übertragungen, Wiederholungsversuche, doppelte Zustellungen, Zeitüberschreitungen beim Empfänger und empfängerseitige Verarbeitungsfehler. Machen Sie die Abschlussbehandlung idempotent, da eine Assembly Notification oder ein nachgelagertes Ereignis mehr als einmal zugestellt werden kann. Das empfangende System sollte mandantenfremden Kontext auch dann zurückweisen, wenn es einem Client gelungen ist, nicht geheime Metadaten zu verändern.
Protokollieren Sie die Assembly-ID, die Zielendpunktklasse und die Asset-ID des Empfängers, ohne Autorisierungsheader zu protokollieren. Das rund 24-stündige Zeitfenster gilt nur für Transloadits temporäre Kopie des Assembly-Ergebnisses, gleichen Sie das empfangende System also ab, bevor diese Kopie abläuft. Betrachten Sie das Produkt-Asset erst dann als fertig, wenn das erwartete Assembly-Ergebnis zugestellt wurde und der Empfänger den beabsichtigten dauerhaften oder veröffentlichten Zustand bestätigt. Genau dieser explizite Abgleich macht aus einer erfolgreichen Protokollübergabe einen zuverlässigen Anwendungs-Workflow.
Wissenswerte technische Details
/tus/storeexportiert die vonuseausgewählten Dateien an die erforderliche URL in seinem Parameterendpoint.- Der Robot akzeptiert HTTP-Template-Zugangsdaten, sodass statische Autorisierungsheader an das Ziel gesendet werden können, ohne in den Instructions zu erscheinen.
- Optionale dynamische
headerswerden an das Ziel gesendet, aber im Browser sichtbare Geheimnisse blieben dabei exponiert und sollten vermieden werden. - Der Robot setzt die Metadatenschlüssel
filename,basenameundextensionstets anhand der verarbeiteten Datei und überschreibt dabei vom Aufrufer übergebene Werte für diese Schlüssel; anderemetadata-Schlüssel werden unverändert wie angegeben durchgereicht. - Fehlt
url_template, verwendet das Ergebnis die vom tus-Zielserver gelieferte Upload-URL. - Fehlt
ssl_url_template, füllt die Ziel-Upload-URL das Feldssl_urldes Ergebnisses nur dann, wenn diese URL mit HTTPS beginnt. /image/optimizelässt nicht unterstützte Bildtypen unverändert durch, validieren Sie Eingaben also, wenn das Ziel ein optimiertes Ergebnis benötigt./video/encodeakzeptiert Voreinstellungen wieweb/mp4/720p, und jede Voreinstellung muss gegen die Wiedergabeanforderungen des Ziels getestet werden.- Transloadit löscht temporäre Assembly-Ergebnisdateien normalerweise rund 24 Stunden nach der Verarbeitung, während aktueller Speicher sie unabhängig von benutzerdefinierten Aufbewahrungseinstellungen mindestens 24 Stunden lang behält; die dauerhafte Aufbewahrung obliegt dem empfangenden tus-Ziel.
Ein praxisnaher Ansatz
- 1
Bestätigen Sie, dass das Ziel das tus-Protokoll implementiert, und legen Sie fest, was nach einem abgeschlossenen Upload geschieht.
- 2
Erstellen Sie HTTP-Template-Zugangsdaten für statische Ziel-Header und speichern Sie separate Templates für Upload, Bild und Video.
- 3
Testen Sie Authentifizierung, Wiederherstellung nach unterbrochener Übertragung, doppelte Zustellung, Verhalten der Ergebnis-URL und die Persistenz auf Empfängerseite.
- 4
Erfassen Sie die Assembly-ID zusammen mit der stabilen Asset-Identität des empfangenden Systems und gleichen Sie den Abschluss idempotent ab.
Wann Transloadit hilfreich ist
Verwenden Sie /tus/store, wenn ein bestehendes Ziel tus-Uploads akzeptiert und eine Transloadit-Assembly ein Original oder ein verarbeitetes Ergebnis dorthin liefern soll. Verwenden Sie einen anbieterspezifischen Speicher-Robot, wenn Transloadit eine Bucket-API und anbieterspezifische Zugriffseinstellungen verstehen soll.
Architekturgrenze
/tus/store übergibt ein ausgewähltes Assembly-Ergebnis an einen tus-kompatiblen Endpunkt. tus definiert die fortsetzbare Übertragung, nicht die Dauerhaftigkeit, das Autorisierungsmodell, die Aufbewahrung, den Veröffentlichungsstatus oder die endgültige Download-URL des Ziels; diese Verantwortung liegt beim empfangenden Dienst und Ihrer Anwendung.
Häufig gestellte Fragen
Lädt der Browser direkt zu meinem tus-Endpunkt hoch?
Nein. Der Browser lädt in diesen Rezepten zu einer Transloadit-Assembly hoch. Nach der Verarbeitung agiert /tus/store als tus-Client und lädt das ausgewählte Ergebnis zu Ihrem konfigurierten Endpunkt hoch. Die beiden Übertragungen haben eigene URLs, Zugangsdaten, Fortschrittsanzeigen und Wiederholungsgrenzen.
Garantiert ein erfolgreicher tus-Upload dauerhaften Speicher?
Nein. tus standardisiert die fortsetzbare Übertragung. Der empfangende Server entscheidet, ob der abgeschlossene Upload dauerhaft gespeichert wird, wie lange er aufbewahrt wird, wer darauf zugreifen kann und ob die Upload-URL auch eine Download-URL ist. Gleichen Sie einen Datensatz auf Empfängerseite ab, statt diese Eigenschaften aus dem Protokollabschluss abzuleiten.
Wie sollte das Ziel Transloadit authentifizieren?
Verwenden Sie den HTTP-Zugangsdatentyp für statische Autorisierungs-Header und referenzieren Sie den Namen der Zugangsdaten in /tus/store. Dynamische headers werden für Fälle unterstützt, in denen statische Zugangsdaten nicht ausreichen, aber platzieren Sie niemals sensible Header in browserseitig sichtbaren Assembly Instructions.
Kann ein Template Dateien, Bilder und Videos verarbeiten?
Verwenden Sie separate Templates, wenn sich Validierungs- und Fehlerrichtlinien unterscheiden. Ein bewusst gemischtes Template kann anhand des erkannten Medientyps filtern und verzweigen und dann jedem /tus/store-Step nur das Ergebnis geben, das dessen Zweig erzeugt.
Welche URL erscheint im Assembly-Ergebnis?
Standardmäßig verwendet der Robot die vom tus-Server zurückgegebene Upload-URL. url_template und ssl_url_template können gemeldete URLs formen, beweisen aber nicht, dass die URL öffentlich lesbar ist oder stabil bleibt. Prüfen Sie den URL-Vertrag des Empfängers unabhängig davon.