driveItem: createUploadSession

Namespace: microsoft.graph

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 sequenzielle API-Anforderungen hochzuladen. Außerdem kann die Übertragung fortgesetzt werden, wenn die Verbindung während des Uploads getrennt 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.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ✅

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. 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.

Hinweis

Das Ersetzen des Inhalts einer Datei, die durch eine Vertraulichkeitsbezeichnung geschützt ist, wird bei der Nur-App-Authentifizierung nicht unterstützt. Verwenden Sie stattdessen delegierte Berechtigungen (Benutzerkontext).

Hinweis

SharePoint Embedded benötigt die FileStorageContainer.Selected Berechtigung für den Zugriff auf den Inhalt des Containers. Diese Berechtigung unterscheidet sich von den zuvor erwähnten. Zusätzlich zu den Microsoft Graph-Berechtigungen muss Ihre App über die erforderlichen Containertypberechtigungen verfügen, um diese API aufzurufen. Weitere Informationen finden Sie unter SharePoint Embedded-Authentifizierung und -Autorisierung.

HTTP-Anforderung

Um eine neue Datei hochzuladen, müssen Sie sowohl die übergeordnete ID als auch den neuen Dateinamen in der Anforderung angeben. Für eine Aktualisierung muss jedoch nur die ID des Elements aktualisiert werden.

Neue Datei erstellen

POST /drives/{driveId}/items/{parentItemId}:/{fileName}:/createUploadSession
POST /groups/{groupId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /users/{userId}/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 /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 der bereitgestellte eTag (oder cTag) nicht mit dem aktuellen etag auf dem Element übereinstimmt, wird eine 412 Precondition Failed Fehlerantwort zurückgegeben.
if-none-match etag Wenn dieser Anforderungsheader enthalten ist und der bereitgestellte eTag (oder cTag) mit dem aktuellen etag auf dem 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 über die hochgeladene Datei bereitzustellen und die Semantik des Uploadvorgangs anzupassen.

Mit der item-Eigenschaft lassen sich beispielsweise die folgenden Parameter festlegen:

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

Das folgende Beispiel steuert das Verhalten, wenn der Dateiname bereits vergeben ist. Das Beispiel gibt auch an, dass die endgültige Datei erst erstellt werden soll, wenn eine explizite Abschlussanforderung gesendet wird.

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  },
  "deferCommit": true
}
Eigenschaft Typ Beschreibung
deferCommit Boolescher Wert Wenn festgelegt auf true, erfordert die endgültige Erstellung der Datei im Ziel eine explizite Anforderung.
item driveItemUploadableProperties Daten zur hochgeladenen Datei.

Antwort

Bei erfolgreicher Ausführung liefert die Antwort auf diese Anforderung die Details dazu, wohin die restlichen Anforderungen als uploadSession-Ressource gesendet werden sollen.

Wenn eine Sitzung erstellt wird und vorab authentifizierte Upload-URLs generiert, kann die Upload-URL verwendet werden, um den Upload innerhalb eines Zeitfensters abzuschließen, das für große Dateien ausreicht.

Die uploadSession-Ressource gibt an, wohin die einzelnen Bytebereiche der Datei hochgeladen werden sollen, und gibt an, wann die Sitzung abläuft. Die Eigenschaft expirationDateTime gibt den Zeitpunkt an, zu dem die aktuelle Sitzung abläuft, wenn keine weiteren Aktivitäten ausgeführt werden. Dies führt zu folgendem Verhalten:

  • Sie müssen das nächste Fragment hochladen oder die Sitzung vor dem in der Eigenschaft expirationDateTime angegebenen Zeitpunkt festschreiben.
  • Jedes hochgeladene Fragment verlängert die Ablaufzeit, sodass große Dateiuploads erfolgreich abgeschlossen werden können. Die aktualisierte Ablaufzeit wird bei jeder Anforderung zum Hochladen eines Dateifragments zurückgegeben.
  • Wenn keine Fragmente empfangen werden und die Sitzung nicht committet wird, werden alle zuvor hochgeladenen Fragmente verworfen.

Dieser Prozess unterstützt große Dateiuploads und stellt sicher, dass Uploadsitzungen effizient verwaltet werden, indem verhindert wird, dass veraltete oder verlassene Daten zu lange im System verbleiben.

Wenn der fileSize Parameter angegeben ist und das verfügbare Kontingent überschreitet, wird eine 507 Insufficient Storage Antwort zurückgegeben und die Uploadsitzung wird nicht erstellt.

Beispiele

Beispiel 1: 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 wurde, wird die Upload-Sitzung abgeschlossen und die endgültige Datei wird im Zielordner angezeigt. Alternativ können Sie die endgültige Erstellung der Datei im Ziel zurückstellen, bis Sie explizit eine Anforderung zum Abschließen des Uploads stellen, indem Sie die deferCommit-Eigenschaft in den Anforderungsargumenten festlegen.

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

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

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

Beispiel 2: 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 einer anderen 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 geteilt wird, führt dazu, dass beim Commit einiger Dateien Fehler auftreten.

Anforderung

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 mit den Microsoft Graph SDKs.
  • Ihre App muss sicherstellen, dass die im Header angegebene Content-Range Gesamtdateigröße für alle Anforderungen gleich ist. Wenn ein Bytebereich eine andere Dateigröße deklariert, schlägt die Anforderung fehl.

Antwort

Wenn die Anforderung abgeschlossen ist, antwortet 202 Accepted der Server, ob 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 erhalten 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 Bytebereich zum Hochladen zurückgibt. Die nextExpectedRanges-Eigenschaft gibt Bereiche der Datei an, die nicht empfangen wurden, und kein Muster, wie Ihre App die Datei hochladen soll.

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

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

Hinweise

  • Die nextExpectedRanges-Eigenschaft listet nicht immer alle fehlenden Bereiche auf.
  • Bei erfolgreichen Fragmentschreibvorgängen wird der nächste Bereich zurückgegeben, mit dem begonnen 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. Um eine detailliertere Liste der fehlenden Bereiche zu erhalten, können Sie den Upload-Status anfordern.
  • Wenn Sie den Authorization Header beim Ausgeben des PUT-Aufrufs einschließen, kann dies zu einer HTTP 401 Unauthorized Antwort führen. Schließen Sie das Header- und Bearertoken Authorization nur ein, wenn Sie die POST-Anforderung im ersten Schritt ausgeben. Schließen Sie sie nicht ein, wenn Sie den PUT-Aufruf ausgeben.

Beispiel 3: Abschließen einer Datei (deferCommit ist false)

Wenn deferCommit festgelegt oder nicht festgelegt ist false , wird der Upload automatisch abgeschlossen, wenn der letzte Bytebereich der Datei in die Upload-URL eingefügt wird.

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

Anforderung

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

<final bytes of the file>

Hinweis

Antwort

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

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

Beispiel 4: Abschließen einer Datei (deferCommit ist false)

Wenn deferCommit den Wert hat true, können Sie den Upload auf zwei Arten explizit abschließen:

  • 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 letzte Anforderung mit einem HTTP 201 Created oder .HTTP 200 OK Der Antworttext enthält auch die Standardeigenschaft, die für das driveItem festgelegt wurde, das die abgeschlossene Datei darstellt.

Anforderung

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

Hinweis

Antwort

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

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

Beispiel 5: 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

Beispiel 6: 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.

Anforderung

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

Antwort

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

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

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.

Beispiel 7: Behandeln von Uploadfehlern

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

Um die Uploadsitzung explizit zu committen, muss Ihre App eine PUT-Anforderung mit einer neuen driveItem-Ressource ausführen, die beim Commit der Uploadsitzung verwendet werden soll. 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.

Anforderung

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

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

Antwort

Wenn für die Datei mit den neuen Metadaten ein Commit ausgeführt werden kann, wird eine HTTP 201 Created ODER-Antwort HTTP 200 OK mit den Item-Metadaten 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 Back-Off-Strategie verwenden, sondern die Anzahl der Wiederholungsversuche 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. 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

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.",
  }
}

Einzelheiten zur Rückgabe von Fehlern finden Sie im Artikel zu Fehlerantworten .

Verwandte Inhalte

Hochladen großer Dateien

  • Last updated on