Wenn Benutzer Dateien von ihrem Gerät hochladen, kann jede Netzwerkunterbrechung oder jedes Serverproblem dazu führen, dass der Upload fehlschlägt. In der Regel muss dann die gesamte Datei erneut übertragen werden. Fortsetzbare Uploads können nach solchen Unterbrechungen nahtlos fortgesetzt werden und bieten eine robustere, effizientere und angenehmere Benutzererfahrung.

Transloadit bietet zwei Möglichkeiten, Dateien auf unsere Server hochzuladen:

Dateien können beim Erstellen einer Assembly in die multipart/form-data-POST-Anfrage aufgenommen werden. Jede Unterbrechung dieser Anfrage führt dazu, dass die Uploads und die Assembly fehlschlagen.
Dateien können mit dem tus-Protokoll für fortsetzbare Uploads hochgeladen werden. Uploads können nach Netzwerk- oder Serverproblemen fortgesetzt werden. Außerdem können Benutzer die Uploads nach Belieben pausieren und fortsetzen. tus ist ein offenes und kostenloses Protokoll für fortsetzbare Datei-Uploads über HTTP mit vielen Open-Source-Client-Implementierungen, die Sie verwenden können.

Dieses Dokument beschreibt die API hinter der zweiten Möglichkeit mit fortsetzbaren Uploads. Sie besteht aus zwei Phasen, die in diesem Dokument beschrieben werden.

Ein Beispiel für Upload → Verarbeitung → private Speicherung sowie ein Testverfahren für kontrollierte Unterbrechungen finden Sie im Workflow für große Videos im Leitfaden zur Datei-Upload-API. Das Fortsetzen der Übertragung garantiert nicht, dass die Verarbeitung oder der Export erfolgreich ist. Bewahren Sie die Assembly ID auf, prüfen Sie den abschließenden Assembly Status und überprüfen Sie die gespeicherten Ausgaben, bevor Sie ein Asset veröffentlichen. Die Einstellungen für erneute Versuche im Client und die Wiederaufnahme nach einem Neuladen sind vom tus-Protokoll selbst unabhängig.

Ein Beispiel für einen Java-Client finden Sie im DevTip zu fortsetzbaren Dateiübertragungen mit tus-java-client. Die Tutorials zu Datei-Uploads (English) behandeln auch HTML-Formulare und benutzerdefinierte Browseroberflächen.

Hinweis

Viele fertige Integrationen, etwa das Node SDK oder Uppy, verwenden standardmäßig im Hintergrund tus, um Dateien hochzuladen. Wenn Sie eine davon verwenden, müssen Sie fortsetzbare Uploads nicht selbst implementieren. Diese Dokumentation richtet sich an Personen, die entweder SDKs entwickeln, SDKs ohne tus-Integration verwenden oder ganz auf ein von Transloadit bereitgestelltes SDK verzichten möchten.

Phase 1: Eine neue Assembly erstellen

Eine neue Assembly wird erstellt, indem eine multipart/form-data-POST-Anfrage an den Endpunkt zum Erstellen von Assemblies gesendet wird. Bei herkömmlichen Uploads würden alle Dateien als zusätzliche Teile in diese Anfrage aufgenommen. Bei fortsetzbaren Uploads nimmt der Client die Dateien nicht in diese Anfrage auf, sondern teilt der Transloadit API lediglich mit, wie viele Dateien hochgeladen werden sollen.

Dazu wird das Feld num_expected_upload_files zur Multipart-POST-Anfrage hinzugefügt. Sein Wert ist die Anzahl der Dateien, die der Client für diese Assembly hochladen möchte. Zusätzliche Felder zur Steuerung der Assembly Instructions, etwa params, müssen ebenfalls enthalten sein.

Der folgende Ausschnitt enthält eine beispielhafte HTTP-Anfrage. Der Client übermittelt die Authentifizierungsdaten und die Assembly Instructions im Feld params. Das Feld num_expected_upload_files gibt an, dass der Client zwei Dateien hochladen möchte. Der eigentliche Inhalt dieser Dateien ist jedoch nicht in dieser Anfrage enthalten.

POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIAWBI8vxocZzsG03

------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="params"

{"auth":{"key":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"},"steps":{"encode":{"robot":"/image/resize"}}}
------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="num_expected_upload_files"

2
------WebKitFormBoundaryIAWBI8vxocZzsG03--

Wenn die Assembly erfolgreich erstellt wurde, antwortet die API mit der entsprechenden Assembly Status-Antwort, die wie dieser Beispielausschnitt aussieht:

{
    "ok": "ASSEMBLY_UPLOADING",
    "assembly_id": "b841ea401e1a11e7b37d7bda1b503cdd",
    "assembly_ssl_url": "https://api2-freja.transloadit.com/assemblies/b841ea401e1a11e7b37d7bda1b503cdd",
    "websocket_url": "https://api2-freja.transloadit.com/ws20277",
    "tus_url": "https://api2-freja.transloadit.com/resumable/files/",
    "expected_tus_uploads": 2,
    "started_tus_uploads": 0,
    "finished_tus_uploads": 0,
    // …
}

Wir sehen, dass sich die Assembly im Upload-Zustand befindet und bereit ist, Uploads zu empfangen. Die Antwort enthält die Eigenschaft assembly_ssl_url, die diese Assembly eindeutig identifiziert. Sie enthält außerdem die Eigenschaft tus_url, die den Endpunkt angibt, an den die Dateien hochgeladen werden sollen. Die Eigenschaften expected_tus_uploads, started_tus_uploads und finished_tus_uploads beschreiben, wie viele Dateien Transloadit für diese Assembly erwartet und wie viele Uploads gestartet bzw. abgeschlossen wurden.

Phase 2: Jede Datei hochladen

Nachdem die Assembly in der ersten Phase erstellt wurde, kann der Client nun damit beginnen, Dateien auf den Server von Transloadit für fortsetzbare Uploads hochzuladen.

Hinweis

Transloadit unterstützt Dateigrößen bis zu 200 GB. Wenn Sie für Ihre Anwendung ein höheres Limit benötigen, kontaktieren Sie uns bitte.

Transloadit betreibt einen tus-Server mit der Software tusd. Seine URL wird über die Eigenschaft tus_url im Assembly Status bereitgestellt, wie in der ersten Phase beschrieben. Dieser tus-Upload-Server hält sich an die Protokollspezifikation und ermöglicht tus-Clients das Hochladen von Dateien. Sie können entweder anhand der Spezifikation Ihren eigenen tus-Client implementieren oder eine der Open-Source-Client-Implementierungen in Ihrer Programmiersprache wählen.

Ein Upload über tus erfolgt in zwei Schritten:

Zunächst wird eine Upload-Ressource auf dem tus-Server erstellt. Der Client sendet eine POST-Anfrage und übermittelt die Assembly URL, den Dateinamen und die fieldname-Metadaten. Der Server antwortet mit einer Upload-URL, an die der Client den eigentlichen Dateiinhalt hochladen kann.
Nach Erhalt der Upload-URL sendet der Client eine PATCH-Anfrage mit dem Dateiinhalt an diesen Endpunkt, um den eigentlichen Upload durchzuführen. Sobald die Datei vollständig übertragen wurde, übergibt der tus-Server die Datei nahtlos an Ihre Assembly zur Verarbeitung, ohne dass eine zusätzliche Interaktion erforderlich ist.

Weitere Einzelheiten zur genauen Semantik dieser Interaktion finden Sie in der Protokollspezifikation. Im nächsten Abschnitt konzentrieren wir uns auf die Aspekte, die für die Integration mit Transloadit relevant sind.

Upload erstellen

Im ersten Schritt wird eine Upload-Ressource auf dem tus-Server erstellt, indem eine POST-Anfrage an den in tus_url angegebenen Endpunkt gesendet wird. Spezielle Metadaten müssen enthalten sein, um den Upload der zuvor erstellten Assembly zuzuordnen. Insgesamt müssen drei Werte in den Metadaten vorhanden sein:

assembly_url: die Assembly URL aus der Eigenschaft assembly_ssl_url im Assembly Status aus der ersten Phase
filename: der Name der Datei
fieldname: das Äquivalent zu den Namen von Eingabefeldern in HTML-Formularen

Alle zusätzlichen Metadaten werden als Assembly Variable in file.user_meta abgelegt. Damit können Sie in Ihrem Template dynamische Aktionen pro Datei ausführen, als Alternative zu fields, das von allen Dateien in einer Assembly gemeinsam genutzt wird. Wenn Sie anhand erkannter Inhalte verzweigen müssen, verwenden Sie vorzugsweise ${file.mime} und prüfen Sie auf MIME-Familien wie image/*, video/* oder audio/*. ${file.type} ist in der Assembly Status-Antwort ebenfalls als grobe Dateikategorie verfügbar. Sein Wert ist einer der folgenden: "audio", "document", "image", "office", "pdf", "swf", "video", "xls" oder null, wenn keine Kategorie erkannt wurde. Anwendungen, die diesen Wert auswerten, sollten auch andere Zeichenfolgenwerte akzeptieren, damit zukünftige Kategorien kompatibel bleiben. Die Prüfung des MIME-Typs ist in der Regel präziser.

In der folgenden Beispielanfrage laden wir eine Datei namens isaac.png mit einer Größe von 10.000 Bytes in die Assembly mit der ID b841ea401e1a11e7b37d7bda1b503cdd und dem Feldnamen file-input hoch. Die genauen Einzelheiten der Metadatenkodierung mit Base64 sind in der Protokollspezifikation beschrieben.

POST /resumable/files/ HTTP/1.1
Content-Length: 0
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Length: 10000
Upload-Metadata: assembly_url aHR0cHM6Ly9hcGkyLWZyZWphLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzL2I4NDFlYTQwMWUxYTExZTdiMzdkN2JkYTFiNTAzY2Rk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==

Bei einer korrekten Anfrage erstellt der Server eine Upload-Ressource und gibt deren Upload-URL im Location-Header zurück. Zum Beispiel:

HTTP/1.1 201 Created
Tus-Resumable: 1.0.0
Location: https://api2-freja.transloadit.com/resumable/files/136058f2ef4dc9de3f5c23ceed591545

Datenübertragung

Nach dem Erstellen des Uploads muss der Client den eigentlichen Dateiinhalt mit einer PATCH-Anfrage an die tus-Upload-URL hochladen:

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Length: 10000
Content-Type: application/offset+octet-stream

[content of file]

Sobald ein tus-Upload abgeschlossen ist, verarbeitet Transloadit ihn automatisch mit den Parametern, die Sie zum Erstellen der Assembly verwendet haben, ohne dass Sie etwas Besonderes tun müssen. Bis alle tus-Uploads abgeschlossen sind, verbleibt die Assembly im Zustand ASSEMBLY_UPLOADING, auch wenn einige der Dateien bereits verarbeitet wurden.

Diese Schritte werden für jede Datei wiederholt, die der Client hochladen möchte. Der Client kann frei entscheiden, ob diese Dateien je nach den Anforderungen der Anwendung parallel oder nacheinander hochgeladen werden.

Die erwartete Anzahl von Uploads teilt der Assembly mit, wie viele Dateien vollständig hochgeladen werden müssen. Sie ist kein striktes Limit für die Anzahl der tus-Upload-Ressourcen, die erstellt werden können. Zusätzliche Ressourcen werden toleriert, solange sich die Assembly im Upload-Zustand befindet, damit ein Client den Vorgang fortsetzen kann, wenn eine Antwort auf die Erstellung eines Uploads verloren gegangen ist. Die Fortschrittszähler berücksichtigen die Uploads mit dem größten Fortschritt in der erwarteten Anzahl, wobei aufgegebene Ressourcen ausgeschlossen werden. Laden Sie nur die vorgesehenen Dateien hoch und verwenden Sie beim Fortsetzen jede bekannte Upload-URL erneut. Sobald die Assembly den Zustand ASSEMBLY_UPLOADING verlässt, wird die Erstellung neuer Uploads abgelehnt.

Upload fortsetzen

Wenn die Datenübertragung fehlschlägt, weil die Netzwerkverbindung unterbrochen wurde oder der Benutzer den Upload pausiert hat, kann der Client den Upload an der Stelle fortsetzen, an der er angehalten wurde.

Zunächst sendet der Client eine HEAD-Anfrage an die Upload-URL, um festzustellen, wie viele Daten der Server vor der Unterbrechung empfangen konnte:

HEAD /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0

Die Antwort enthält die Anzahl der empfangenen Bytes im Upload-Offset-Header. Die folgende Antwort zeigt beispielsweise einen Upload, bei dem 3.000 von 10.000 Bytes empfangen wurden:

HTTP/1.1 200 OK
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Upload-Length: 10000

Die verbleibenden 7.000 Bytes können dann mit einer weiteren PATCH-Anfrage hochgeladen werden:

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream

[remaining content of file]

Weitere Informationen zu fortsetzbaren Uploads mit tus finden Sie in den tus-FAQ.