Freigeben über

driveItem: createUploadSession

  • Artikel

Namespace: microsoft.graph

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. Uploadsitzungen ermöglichen es auch, die Übertragung fortzusetzen, wenn eine Verbindung unterbrochen wird, während der Upload ausgeführt wird.

So laden Sie eine Datei mithilfe einer Uploadsitzung hoch:

  1. Erstellen einer Uploadsitzung
  2. Hochladen von Bytes in die Uploadsitzung

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ✅

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
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 Nicht verfügbar.

Erstellen einer Uploadsitzung

Um eine große Datei hochladen zu können, muss die App zuerst eine neue Uploadsitzung anfordern. Diese Anforderung erstellt einen temporären Speicherort, an dem die Bytes der Datei gespeichert werden, bis die vollständige Datei hochgeladen wird. Wenn das letzte Byte der Datei hochgeladen wird, wird die Uploadsitzung abgeschlossen, und die endgültige Datei wird im Zielordner angezeigt. Alternativ können Sie die endgültige Erstellung der Datei im Ziel verzögern, bis Sie explizit eine Anforderung zum Abschließen des Uploads stellen, indem Sie die deferCommit-Eigenschaft in den Anforderungsargumenten festlegen.

HTTP-Anforderung

Um eine neue Datei hochzuladen, müssen Sie sowohl die übergeordnete ID als auch den neuen Dateinamen in der Anforderung angeben. Ein Update erfordert jedoch nur die ID des Elements, das aktualisiert wird.

Neue Datei erstellen

POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession

Vorhandene Datei aktualisieren

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

Anforderungsheader

Name Wert Beschreibung
if-match etag Wenn dieser Anforderungsheader enthalten ist und das angegebene eTag (oder cTag) nicht mit dem aktuellen eTag für das Element übereinstimmt, wird eine 412 Precondition Failed Fehlerantwort zurückgegeben.
if-none-match etag Wenn dieser Anforderungsheader enthalten ist und das angegebene eTag (oder cTag) mit dem aktuellen eTag für das Element übereinstimmt, wird eine 412 Precondition Failed Fehlerantwort zurückgegeben.

Anforderungstext

Es ist kein Anforderungstexts erforderlich. Sie können jedoch Eigenschaften im Anforderungstext angeben, um weitere Informationen zur hochgeladenen Datei bereitzustellen und die Semantik des Uploadvorgangs anzupassen.

Die Item-Eigenschaft ermöglicht beispielsweise das Festlegen der folgenden Parameter:

{
  "@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 gesteuert, wenn der Dateiname bereits verwendet wird. Das Beispiel gibt auch an, dass die endgültige Datei erst erstellt werden soll, wenn eine explizite Vervollständigungsanforderung 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 für das Element übereinstimmt, wird eine 412 Precondition Failed Fehlerantwort zurückgegeben.

Parameter

Parameter Typ Beschreibung
deferCommit Boolescher Wert Bei Festlegung auf trueist für die endgültige Erstellung der Datei im Ziel eine explizite Anforderung erforderlich.
item driveItemUploadableProperties Daten zur hochgeladenen Datei.

Anforderung

Die Antwort auf diese Anforderung enthält die Details der neu erstellten uploadSession, die die URL enthält, die zum Hochladen der Teile der Datei verwendet wird.

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

POST /me/drive/items/{itemID}:/{item-path}:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@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 fileSize Parameter angegeben ist 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

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. Das Hochladen von Fragmenten in falscher Reihenfolge führt zu einem Fehler.

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.

Die Verwendung einer Fragmentgröße, die nicht gleichmäßig durch 320 KiB dividiert wird, führt zu Fehlern beim Committen einiger Dateien.

Beispiel

In diesem Beispiel lädt die App die ersten 26 Bytes 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>

Hinweis

  • Informationen zum Hochladen großer Dateien mithilfe von SDKs finden Sie unter Hochladen großer Dateien mithilfe der Microsoft Graph SDKs.
  • Ihre App muss sicherstellen, dass die im Content-Range-Header angegebene Gesamtdateigröße für alle 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 weitere Bytebereiche 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. Möglicherweise werden mehrere Bereiche angegeben, die Teile der Datei angeben, 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 Bereiche der richtigen Größe für einen hochzuladenden Bytebereich zurückgibt. Die nextExpectedRanges-Eigenschaft gibt Bereiche der Datei an, die nicht empfangen wurden, und kein Muster für das Hochladen der Datei durch Ihre App.

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

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

Bemerkungen

  • Die nextExpectedRanges -Eigenschaft listet nicht immer alle fehlenden Bereiche auf.
  • Bei erfolgreichen Fragmentschreibvorgängen wird der nächste Bereich zurückgegeben, von dem aus gestartet werden soll (z. B. "523-").
  • Bei Fehlern, bei denen 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 beim Ausgeben des Aufrufs PUT einschließen, kann dies zu einer HTTP 401 Unauthorized Antwort führen. Senden Sie den Autorisierungsheader und das Bearertoken nur beim Ausgeben des POST während des ersten Schritts. Schließen Sie sie nicht ein, wenn Sie den PUT Anruf ausgeben.

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 auf die endgültige Anforderung mit oder HTTP 201 CreatedHTTP 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>

Hinweis

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

Hinweis

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": "nameAlreadyExists",
    "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

Zum Abbrechen einer Uploadsitzung 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 möglicherweise nicht sofort nach Ablauf der Ablaufzeit gelöscht.

Anforderung

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

Hinweis

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 hochgeladen werden müssen, und der Ablaufzeit für die Uploadsitzung.

Hinweis

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, sodass Ihre App den Upload wiederherstellen kann, indem sie die Uploadsitzung explizit committen.

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 https://graph.microsoft.com/v1.0/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}"
}

Antwort

Wenn die Datei mit den neuen Metadaten committet werden kann, wird eine HTTP 201 Created - oder HTTP 200 OK -Antwort 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 keine exponentielle Backoff-Strategie verwenden, sondern die Anzahl von Wiederholungsversuchen begrenzen.
  • 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. Für langsamere oder weniger zuverlässige Verbindungen erhalten Sie möglicherweise bessere Ergebnisse bei einer kleineren Fragmentgröße. 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

Ausführliche Informationen zur Rückgabe von Fehlern finden Sie im Artikel Fehlerantworten .

Verwandte Inhalte

Hochladen großer Dateien