driveItem: createUploadSession

Artikel
07/01/2022
9 Minuten Lesedauer

Namespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können geändert werden. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in Version 1.0 verfügbar ist, verwenden Sie die Versionsauswahl .

Wenn Sie eine Uploadsitzung erstellen, kann Ihre App Dateien bis zur maximal zulässigen Dateigröße hochladen.

Mit einer Uploadsitzung kann Ihre App Bereiche der Datei in sequenziellen API-Anforderungen hochladen, wodurch die Übertragung fortgesetzt werden kann, wenn eine Verbindung unterbrochen wird, während der Upload ausgeführt wird.

So laden Sie eine Datei mithilfe einer Uploadsitzung hoch:

Erstellen einer Uploadsitzung
Hochladen von Bytes in die Uploadsitzung

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema 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. Sobald das letzte Byte der Datei hochgeladen wurde, ist die Uploadsitzung abgeschlossen, und die endgültige Datei wird im Zielordner angezeigt. Alternativ können Sie die endgültige Erstellung der Datei im Zielordner zurückstellen, bis Sie eine explizite Anforderung zum Abschließen des Uploads stellen. Dafür legen Sie die Eigenschaft "deferCommit" in den Anforderungsargumenten fest.

HTTP-Anforderung

POST /drives/{driveId}/items/{itemId}/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 Anforderungstext erforderlich. Sie können jedoch Eigenschaften im Anforderungstext angeben, die zusätzliche Daten für die hochzuladende Datei bereitstellen und die Semantik des Uploadvorgangs anpassen.

So lassen sich beispielsweise mit der Eigenschaft “item” folgende Parameter festlegen:

{
  "@microsoft.graph.conflictBehavior": "fail (default) | replace | rename",
  "description": "description",
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234,
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

Im folgenden Beispiel wird das Verhalten festgelegt, wenn der Dateiname bereits verwendet wird. Es wird außerdem angegeben, dass die endgültige Datei erst erstellt werden soll, wenn eine explizite Abschlussanforderung gestellt wird:

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  },
  "deferCommit": true
}

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.

Parameter

Parameter	Typ	Beschreibung
deferCommit	Boolescher Wert	Wenn diese Einstellung festgelegt `true`ist, erfordert die endgültige Erstellung der Datei im Ziel eine explizite Anforderung.
item	driveItemUploadableProperties	Daten über die Datei, die hochgeladen wird.

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.

Hinweis: Der {item-path} muss den Namen des Elements enthalten, das im Anforderungstext angegeben ist.

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.

Wenn der Parameter fileSize angegeben wurde und das verfügbare Kontingent überschreitet, wird eine “507 Insufficent Storage”-Antwort zurückgegeben, und die Uploadsitzung wird nicht erstellt.

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

Um die Datei oder einen Teil der Datei hochzuladen, stellt Ihre App eine PUT-Anforderung an den erhaltenen uploadUrl-Wert in der createUploadSession-Antwort. Sie können die gesamte Datei hochladen oder die Datei in mehrere Bytebereiche aufteilen, solange die maximale Anzahl an Bytes in einer bestimmten Anforderung weniger als 60 MB beträgt.

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 Bytebereiche aufteilt, MUSS die Größe jedes Bytebereichs ein Vielfaches von 320 KiB (327.680 Byte) sein. Die Verwendung einer Fragmentgröße, die sich nicht gleichmäßig durch 320 KiB teilen lässt, führt zu Fehlern beim Übertragen einiger Dateien.

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 Bereichen 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 Bytebereiche immer an die unten beschriebenen bewährten Methoden. Gehen Sie nicht davon aus, dass nextExpectedRanges richtig dimensionierte Bereiche für den Upload eines Bytebereich zurückgeben wird. Die Eigenschaft nextExpectedRanges gibt Dateibereiche an, die noch nicht empfangen wurden. Sie ist nicht als Muster für den Dateiupload Ihrer 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.
Wenn Sie den Autorisierungsheader in den PUT-Aufruf einschließen, wird möglicherweise eine Antwort des Typs HTTP 401 Unauthorized zurückgegeben. Der Autorisierungsheader und das Bearertoken sollten nur mit dem POST-Aufruf im Rahmen von Schritt 1 gesendet werden. Der Autorisierungsheader sollte nicht in den PUT-Aufruf eingeschlossen werden.

Vervollständigen einer Datei

Wenn deferCommit falsch oder nicht festgelegt ist, wird der Upload automatisch abgeschlossen, sobald der letzte Bytebereich der Datei zur Upload-URL PUT ist.

Wenn deferCommit wahr ist, können Sie den Upload explizit auf zwei Arten ausführen:

Nachdem der letzte Bytebereich der Datei auf die Upload-URL PUT ist, senden Sie eine letzte POST-Anforderung mit Inhaltslänge Null an die Upload-URL (wird derzeit nur von OneDrive for Business und SharePoint unterstützt).
Nachdem der letzte Bytebereich der Datei auf die Upload-URL PUT ist, senden Sie eine letzte PUT-Anforderung auf dieselbe Weise, wie Sie auch Uploadfehler behandeln würden (wird derzeit nur von OneDrive Personal unterstützt).

Wenn der Upload abgeschlossen ist, antwortet der Server mit einem HTTP 201 Created oder HTTP 200 OK auf die endgültige Anforderung. Der Antworttext enthält auch die Standardeigenschaft, die für das driveItem festgelegt ist, das die abgeschlossene Datei abbildet.

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": { }
}

POST https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 0

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 wurde, kann möglicherweise 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 manueller 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_file}
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.

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.

Siehe auch

Hochladen großer Dateien

driveItem: createUploadSession

Berechtigungen

Erstellen einer Uploadsitzung

HTTP-Anforderung

Anforderungstext

Optionale Anforderungsheader

Parameter

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

Antwort

Bewährte Methoden

Fehlerantworten

Siehe auch

Feedback