Fortsetzbare Uploads

Wenn Benutzer Dateien von ihrem Gerät hochladen, können Netzwerkunterbrechungen oder Serverprobleme dazu führen, dass der Upload fehlschlägt und in der Regel die gesamte Datei erneut übertragen werden muss. 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 über das fortsetzbare tus-Upload-Protokoll hochgeladen werden. Uploads können nach Netzwerk- oder Serverproblemen fortgesetzt werden. Benutzer können die Uploads außerdem jederzeit pausieren und wieder aufnehmen. tus ist ein offenes und kostenloses Protokoll für fortsetzbare Datei-Uploads über HTTP mit zahlreichen Open-Source-Client-Implementierungen, die Sie nutzen können.

Dieses Dokument beschreibt die API für den zweiten, fortsetzbaren Ansatz. Er besteht aus zwei Phasen, die in diesem Dokument beschrieben werden.

Hinweis

Viele sofort einsetzbare Integrationen wie das Node SDK oder Uppy verwenden standardmäßig im Hintergrund tus, um Dateien hochzuladen. Wenn Sie eine dieser Integrationen 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 vollständig auf ein von Transloadit bereitgestelltes SDK verzichten möchten.

Phase 1: 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 die Anfrage auf, sondern teilt der Transloadit API lediglich mit, wie viele Dateien hochgeladen werden sollen.

Dazu wird das Feld num_expected_upload_files zur mehrteiligen POST-Anfrage hinzugefügt. Sein Wert entspricht der 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 ein Beispiel für eine HTTP-Anfrage. Der Client stellt die Authentifizierungsdaten und die Assembly Instructions im Feld params bereit. 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 zugehörigen 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-Status befindet und Uploads empfangen kann. 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 definiert, zu dem die Dateien hochgeladen werden sollen. Die Eigenschaften expected_tus_uploads, started_tus_uploads und finished_tus_uploads geben an, wie viele Dateien Transloadit für diese Assembly erwartet und wie viele Uploads gestartet bzw. abgeschlossen wurden.

Phase 2: Einzelne Dateien hochladen

Nachdem die Assembly in der ersten Phase erstellt wurde, kann der Client nun mit dem Upload der Dateien auf den Transloadit-Server für fortsetzbare Uploads beginnen.

Hinweis

Transloadit unterstützt Dateigrößen von 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 tusd-Software. Seine URL wird über die Eigenschaft tus_url im Assembly Status bereitgestellt, wie in der ersten Phase beschrieben. Dieser tus-Upload-Server entspricht der Protokollspezifikation und ermöglicht tus-Clients das Hochladen von Dateien. Sie können entweder anhand der Spezifikation einen eigenen tus-Client implementieren oder eine der Open-Source-Client-Implementierungen für Ihre Programmiersprache auswä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 den Dateityp. Der Server antwortet mit einer Upload-URL, zu der 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, leitet der tus-Server sie nahtlos zur Verarbeitung an Ihre Assembly weiter, ohne dass eine weitere Interaktion erforderlich ist.

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

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 enthalten sein:

assembly_url: die Assembly URL aus der Eigenschaft assembly_ssl_url im Assembly Status der ersten Phase
filename: der Dateiname
fieldname: das Gegenstück zu Namen von Eingabefeldern in HTML-Formularen

Alle zusätzlichen Metadaten werden als Assembly Variable in file.user_meta gespeichert. Sie können dies als Alternative zu fields, das von allen Dateien in einer Assembly gemeinsam verwendet wird, nutzen, um in Ihrem Template dynamische Aktionen pro Datei auszuführen. Wenn Sie abhängig von erkannten Inhalten verzweigen müssen, verwenden Sie bevorzugt ${file.mime} und gleichen Sie MIME-Familien wie image/*, video/* oder audio/* ab. ${file.type} ist auch als allgemeine Assembly Status-Kategorie verfügbar, für präzisere Prüfungen empfiehlt sich jedoch meist der MIME-Abgleich.

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 14b1b490447d11e6aba4756b3e9d3a0d und dem Feldnamen file-input hoch. Die genauen Einzelheiten zum Encoding der Metadaten mit Base64 werden 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 aHR0cHM6Ly9hcGkyLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzLzE0YjFiNDkwNDQ3ZDExZTZhYmE0NzU2YjNlOWQzYTBk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==

Bei einer korrekten Anfrage erstellt der Server eine Upload-Ressource und gibt deren Upload-URL im Location-Header zurück. 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 über eine 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 beim Erstellen der Assembly verwendet haben – ohne dass Sie weitere Schritte ausführen müssen. Bis alle tus-Uploads abgeschlossen sind, verbleibt die Assembly im Status ASSEMBLY_UPLOADING, selbst wenn einige Dateien bereits verarbeitet wurden.

Diese Schritte werden für jede Datei wiederholt, die der Client hochladen möchte. Der Client kann je nach Anforderungen der Anwendung frei entscheiden, ob diese Dateien parallel oder nacheinander hochgeladen werden. Wenn Sie einer Assembly mehr tus-Uploads hinzufügen möchten, als Sie beim Erstellen der Assembly angegeben haben, werden die zusätzlichen Uploads ohne Meldung verworfen.

Fortsetzen

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

Zunächst sendet der Client eine HEAD-Anfrage an die Upload-URL, um zu ermitteln, 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 im Header Upload-Offset die Anzahl der empfangenen Bytes. Die folgende Antwort zeigt beispielsweise einen Upload, bei dem 3.000 von 10.000 Bytes empfangen wurden:

HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Upload-Length: 10000

Die verbleibenden 7.000 Bytes können anschließend 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.