Hochladen großer Dateien mit einer Uploadsitzung

Artikel
04/08/2023

Wenn Sie eine Uploadsitzung erstellen, kann Ihre App Dateien bis zur maximal zulässigen Dateigröße hochladen. Eine Uploadsitzung ermöglicht Es Ihrer App, Bereiche der Datei in sequenziellen API-Anforderungen hochzuladen, wodurch die Übertragung fortgesetzt werden kann, wenn eine Verbindung unterbrochen wird, während der Upload ausgeführt wird.

Sie müssen zwei Schritte durchführen, um eine Datei mit einer Uploadsitzung hochzuladen:

Erstellen einer Uploadsitzung
Hochladen von Bytes in die Uploadsitzung

Berechtigungen

Eine der folgenden Berechtigungen ist erforderlich, um diese API aufzurufen. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie unter Berechtigungen.

Berechtigungstyp	Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto)	Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto)	Files.ReadWrite, Files.ReadWrite.All
Anwendung	Sites.ReadWrite.All

Erstellen einer Uploadsitzung

Um eine große Datei hochladen zu können, muss die App zuerst eine neue Uploadsitzung anfordern. Es wird dann ein temporärer Speicherort erstellt, an dem die Bytes der Datei gespeichert werden, bis sie vollständig hochgeladen ist. Geben Sie zum Hochladen einer neuen Datei die ID oder den Pfad des übergeordneten Ordners an. Geben Sie zum Aktualisieren einer vorhandenen Datei die ID oder den Pfad der zu aktualisierenden Datei an. Sobald das letzte Byte der Datei hochgeladen wurde, ist die Uploadsitzung abgeschlossen, und die endgültige Datei wird im Zielordner angezeigt.

HTTP-Anforderung

POST /drives/{driveId}/items/{itemId}/createUploadSession
POST /drives/{driveId}/items/{itemId}:/{fileName}:/createUploadSession
POST /groups/{groupId}/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}/createUploadSession
POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

Anforderungstext

Es ist kein Anforderungstexts erforderlich. Allerdings können Sie eine item-Eigenschaft im Anforderungstext definieren, um zusätzliche Daten zu der hochzuladenden Datei anzugeben.

{
  "@microsoft.graph.conflictBehavior": "rename | fail | replace",
  "description": "description",
  "fileSystemInfo": { "@odata.type": "microsoft.graph.fileSystemInfo" },
  "name": "filename.txt"
}

Beispielsweise können Sie im Anforderungstext die Eigenschaft „conflictBehavior“ definieren, um festzulegen, wie vorgegangen werden soll, wenn der Dateiname bereits anderweitig in Verwendung ist.

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  }
}

Optionale Anforderungsheader

Name	Wert	Beschreibung
if-match	etag	Wenn dieser Anforderungsheader enthalten ist und das angegebene ETag (oder CTag) nicht mit dem aktuellen ETag des Elements übereinstimmt, wird der Fehler `412 Precondition Failed` zurückgegeben.

Eigenschaften

Eigenschaft	Typ	Beschreibung
description	Zeichenfolge	Stellt eine für den Benutzer sichtbare Beschreibung des Elements bereit. Lese-/Schreibzugriff. Nur auf OneDrive Personal
fileSystemInfo	fileSystemInfo	Informationen zum Dateisystem des Clients. Lese-/Schreibzugriff.
name	String	Der Name des Elements (Dateiname und Erweiterung). Lese-/Schreibzugriff.

Anforderung

Die Antwort auf diese Anforderung enthält die Details der neu erstellten Ressource des Typs uploadSession, einschließlich der zum Upload der Dateiteile verwendeten URL.

POST /drive/root:/{item-path}:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@odata.type": "microsoft.graph.driveItemUploadableProperties",
    "@microsoft.graph.conflictBehavior": "rename",
    "name": "largefile.dat"
  }
}

Antwort

Wenn der Vorgang erfolgreich war, liefert die Antwort auf diese Anforderung die Details dazu, wohin die verbleibenden Anforderungen als UploadSession-Ressource gesendet werden sollen.

Diese Ressource gibt Details zu dem Ort an, an dem der Bytebereich hochgeladen werden sollte und wann die Uploadsitzung abläuft.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uploadUrl": "https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337",
  "expirationDateTime": "2015-01-29T09:21:55.523Z"
}

Hochladen von Bytes in die Uploadsitzung

Zum Hochladen der Datei oder eines Teils der Datei sendet die App eine PUT-Anfrage an den Wert uploadUrl, der ihr in der createUploadSession-Antwort übermittelt wurde. Sie können die gesamte Datei hochladen oder die Datei in Fragmente aufteilen, vorausgesetzt, die maximale Bytezahl pro Anforderung bleibt unter 60 MiB.

Die Dateifragmente müssen sequenziell in der richtigen Reihenfolge hochgeladen werden. Werden die Fragmente in der falschen Reihenfolge hochgeladen, tritt ein Fehler auf.

Hinweis: Wenn die App eine Datei in mehrere Fragmente aufteilt, MUSS die Größe jedes Fragments ein Vielfaches von 320 KiB (327.680 Byte) sein. Bei Fragmentgrößen, die sich nicht ohne Rest durch 320 KiB teilen lassen, treten beim Übergeben einiger Dateien Fehler auf.

Beispiel

In diesem Beispiel lädt die App die ersten 26 Byte einer 128-Byte-Datei hoch.

Der Header Content-Length definiert die Größe der aktuellen Anforderung.
Der Header Content-Range gibt den Bytebereich in der Gesamtdatei an, den diese Anforderung repräsentiert.
Die Gesamtlänge der Datei muss bekannt sein, bevor Sie das erste Fragment der Datei hochladen können.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 26
Content-Range: bytes 0-25/128

<bytes 0-25 of the file>

Wichtig: Die App muss sicherstellen, dass die im Header Content-Range angegebene Gesamtdateigröße bei allen Anforderungen identisch ist. Wird für einen Bytebereich eine andere Dateigröße deklariert, schlägt die betreffende Anforderung fehl.

Antwort

Wenn die Anforderung abgeschlossen ist, antwortet der Server mit 202 Accepted, wenn es weitere Bytebereiche, die hochgeladen werden müssen.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["26-"]
}

Die App kann mithilfe des Werts nextExpectedRanges bestimmen, wo der nächste Bytebereich beginnen soll. Eventuell werden mehrere Bereiche angegeben. Sie stehen für Teile der Datei, die der Server noch nicht empfangen hat. Dies ist nützlich, wenn eine Übertragung nach einer Unterbrechung fortgesetzt werden soll und der Client den Dienststatus nicht kennt.

Halten Sie sich bei der Festlegung der Größe der Bytebereiche immer an die unten beschriebenen bewährten Methoden. Gehen Sie nicht davon aus, dass nextExpectedRanges richtig dimensionierte Bytebereiche für einen Upload zurückgibt. Die Eigenschaft nextExpectedRanges gibt Dateibereiche an, die noch nicht empfangen wurden. Sie ist nicht als Muster für den Dateiupload der App zu verstehen.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": [
  "12345-55232",
  "77829-99375"
  ]
}

Hinweise

Die Eigenschaft nextExpectedRanges listet nicht immer alle fehlenden Bereiche auf.
Wird ein Segment geschrieben, gibt sie den nächsten Bereich zurück, ab dem begonnen wird (z. B. „523-“).
Schlägt der Schreibvorgang fehl, weil der Client ein Fragment gesendet hat, das der Server bereits empfangen hat, antwortet der Server mit HTTP 416 Requested Range Not Satisfiable. Sie können den Uploadstatus anfordern, um eine detailliertere Liste der fehlenden Bereiche zu erhalten.
Einschließlich des Autorisierungsheaders bei der Ausgabe von PUT kann der Aufruf zu einer HTTP 401 Unauthorized-Antwort führen. Der Autorisierungsheader und das Bearertoken sollten nur gesendet werden, wenn während des ersten Schritts ausgegeben POST wird. Beim Ausgeben von PUT sollte es nicht eingeschlossen werden.

Vervollständigen einer Datei

Sobald der Server den letzten Bytebereich einer Datei empfängt, antwortet er mit HTTP 201 Created oder HTTP 200 OK. Der Antworttext enthält auch die Standardeigenschaft, die für das DriveItem festgelegt wurde, das die vervollständigte Datei repräsentiert.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 21
Content-Range: bytes 101-127/128

<final bytes of the file>

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Umgang mit Upload-Konflikten

Wenn ein Konflikt auftritt, nachdem die Datei hochgeladen wurde (während der Uploadsitzung wurde beispielsweise ein Element mit demselben Namen erstellt), wird ein Fehler zurückgegeben, wenn der letzte Bytebereich hochgeladen wurde.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error":
  {
    "code": "upload_name_conflict",
    "message": "Another file exists with the same name as the uploaded session. You can redirect the upload session to use a new filename by calling PUT with the new metadata and @microsoft.graph.sourceUrl attribute.",
  }
}

Abbrechen der Uploadsitzung

Wenn Sie eine Uploadsitzung abbrechen möchten, senden Sie eine DELETE-Anforderung an die Upload-URL. Das bereinigt die temporäre Datei, in der die bisher hochgeladenen Daten gespeichert sind. Verwenden Sie diese Vorgehensweise in Szenarios, in denen der Upload abgebrochen wird, beispielsweise bei Abbruch der Übertragung durch den Benutzer.

Temporäre Dateien und die zugehörigen Uploadsitzungen werden automatisch bereinigt, wenn der über expirationDateTime festgelegte Termin abgelaufen ist. Temporäre Dateien werden eventuell nicht sofort gelöscht, nachdem die Ablaufzeit verstrichen ist.

Anforderung

DELETE https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337

Antwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 204 No Content

Fortsetzen eines laufenden Uploads

Wenn während einer Uploadanforderung die Verbindung getrennt wird oder anderweitig ausfällt, bevor die Anforderung abgeschlossen ist, werden alle Bytes in dieser Anforderung ignoriert. Dies kann passieren, wenn die Verbindung zwischen der App und dem Dienst getrennt wird. Tritt ein solcher Fall ein, kann die App die Dateiübertragung trotzdem ab dem letzten vollständig übertragenen Fragment fortsetzen.

Um herauszufinden, welche Bytebereiche bereits empfangen wurden, kann die App den Status der Uploadsitzung anfordern.

Beispiel

Sie können den Status des Uploads anfragen, indem Sie eine GET-Anforderung an uploadUrl senden.

GET https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF86633784148bb98a1zjcUhf7b0mpUadahs

Der Server antwortet mit einer Liste der fehlenden Bytebereiche, die noch hochgeladen werden müssen, sowie mit dem Ablauftermin der Uploadsitzung.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["12345-"]
}

Hochladen von verbleibenden Daten

Die App weiß jetzt, ab wo der Upload gestartet werden soll. Führen Sie nun die Schritte im Abschnitt Hochladen von Bytes in die Uploadsitzung durch, um den Upload fortzusetzen.

Behandeln von Fehlern beim Upload

Wenn der letzte Bytebereich einer Datei hochgeladen wird, kann ein Fehler auftreten. Dies kann an einem Namenskonflikt liegen oder daran, dass eine Kontingenteinschränkung überschritten wurde. Die Uploadsitzung wird bis zur Ablaufzeit beibehalten. Dadurch kann Ihre App den Upload wiederherstellen, indem ein ausdrücklicher Commit der Uploadsitzung durchgeführt wird.

Um ausdrücklich einen Commit für die Uploadsitzung durchzuführen, muss Ihre App eine PUT-Anforderung mit einer neuen driveItem-Ressource durchführen, die für den Commit der Uploadsitzung verwendet wird. Diese neue Anforderung sollte die Quelle der Fehler korrigieren, die den ursprünglichen Uploadfehler verursacht hat.

Um anzugeben, dass Ihre App einen Commit zu einer bestehenden Uploadsitzung durchführt, muss die PUT-Anforderung die @microsoft.graph.sourceUrl-Eigenschaft mit dem Wert Ihrer Uploadsitzungs-URL enthalten.

PUT /me/drive/root:/{path_to_parent}
Content-Type: application/json
If-Match: {etag or ctag}

{
  "name": "largefile.vhd",
  "@microsoft.graph.conflictBehavior": "rename",
  "@microsoft.graph.sourceUrl": "{upload session URL}"
}

Hinweis: Sie können den @microsoft.graph.conflictBehavior- und if-match-Header wie erwartet in diesem Aufruf verwenden.

HTTP-Antwort

Wenn mithilfe der neuen Metadaten ein Commit für die Datei durchgeführt werden kann, wird die Fehlerantwort HTTP 201 Created oder HTTP 200 OK mit den Elementmetadaten für die hochgeladene Datei zurückgegeben.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Bewährte Methoden

Setzen Sie alle Uploads fort bzw. starten Sie alle Uploads neu, die wegen eines Verbindungsabbruchs oder einem 5xx-Fehler fehlschlagen, beispielsweise:
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Verwenden Sie einen Exponential Backoff-Algorithmus, wenn beim Fortsetzen oder Neusenden einer Uploadanforderung 5xx-Serverfehler auftreten.
Bei anderen Fehlern sollten Sie keinen Exponential Backoff-Algorithmus verwenden, sondern stattdessen die Anzahl der Wiederholungsversuche beschränken.
Sollte bei fortsetzbaren Uploads der Fehler 404 Not Found auftreten, starten Sie den gesamten Upload neu. Dies bedeutet, dass die Upload-Sitzung nicht mehr vorhanden ist.
Verwenden Sie fortsetzbare Dateiübertragungen für Dateien, die größer als 10 MiB sind (10.485.760 Byte).
Die optimale Größe eines Bytebereichs für stabile Highspeedverbindungen ist 10 MiB. Bei langsameren oder weniger zuverlässigen Verbindungen liefern kleinere Fragmentgrößen eventuell bessere Ergebnisse. Die empfohlene Fragmentgröße liegt zwischen 5 und 10 MiB.
Verwenden Sie eine Bytebereichsgröße, die ein Vielfaches von 320 KiB ist (327.680 Byte) ist. Wenn Sie eine Fragmentgröße verwenden, die kein Vielfaches von 320 KiB ist, können Übertragungen großer Dateien nach Upload des letzten Bytebereichs fehlschlagen.

Fehlerantworten

Weitere Informationen dazu, wie Fehler zurückgegeben werden, finden Sie unter Fehlerantworten.

Hochladen großer Dateien mit einer Uploadsitzung

Berechtigungen

Erstellen einer Uploadsitzung

HTTP-Anforderung

Anforderungstext

Optionale Anforderungsheader

Eigenschaften

Anforderung

Antwort

Hochladen von Bytes in die Uploadsitzung

Beispiel

Antwort

Hinweise

Vervollständigen einer Datei

Umgang mit Upload-Konflikten

Abbrechen der Uploadsitzung

Anforderung

Antwort

Fortsetzen eines laufenden Uploads

Beispiel

Hochladen von verbleibenden Daten

Behandeln von Fehlern beim Upload

HTTP-Antwort

Bewährte Methoden

Fehlerantworten

Zusätzliche Ressourcen