# 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: 1. Dateien können beim[Erstellen einer Assembly](/de/docs/api/assemblies-post.md) in die `multipart/form-data`-POST-Anfrage aufgenommen werden. Jede Unterbrechung dieser Anfrage führt dazu, dass die Uploads und die Assembly fehlschlagen. 2. Dateien können über das [fortsetzbare Tus-Upload-Protokoll](https://tus.io) 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](https://tus.io/implementations), 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](/de/docs/api/assemblies-post.md) 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. ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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](/de/docs/api/assembly-status-response.md), die wie dieser Beispielausschnitt aussieht: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```jsonc { "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 dieseAssembly 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](mailto:support@transloadit.com) bitte. Transloadit betreibt einen [Tus](https://tus.io)-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](https://tus.io/protocols/resumable-upload)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](https://tus.io/implementations) für Ihre Programmiersprache auswählen. Ein Upload über Tus erfolgt in zwei Schritten: 1. Zunächst wird eine Upload-Ressource auf dem Tus-Server erstellt. Der Client sendet eine[POST-Anfrage](https://tus.io/protocols/resumable-upload#post) 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. 2. Nach Erhalt der Upload-URL sendet der Client eine[PATCH-Anfrage](https://tus.io/protocols/resumable-upload#patch) 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](https://tus.io/protocols/resumable-upload). 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` imAssembly 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](/de/docs/topics/assembly-instructions.md#assembly-variables) 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](https://tus.io/protocols/resumable-upload#upload-metadata) beschrieben. ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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 derAssembly 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```http 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](https://tus.io/faq).