Hochladen großer Dateien mit einer UploadsitzungUpload large files with an upload session

Wenn Sie eine Uploadsitzung erstellen, kann Ihre App Dateien bis zur maximal zulässigen Dateigröße hochladen. Eine Uploadsitzung erlaubt es der App, Bereiche einer Datei in sequenziellen API-Anfragen hochzuladen. Bricht die Verbindung während des Uploads ab, kann die Übertragung so anschließend fortgesetzt werden.Create an upload session to allow your app to upload files up to the maximum file size. An upload session allows your app to upload ranges of the file in sequential API requests, which allows the transfer to be resumed if a connection is dropped while the upload is in progress.

Sie müssen zwei Schritte durchführen, um eine Datei mit einer Uploadsitzung hochzuladen:To upload a file using an upload session, there are two steps:

  1. Erstellen einer UploadsitzungCreate an upload session
  2. Hochladen von Bytes in die UploadsitzungUpload bytes to the upload session

BerechtigungenPermissions

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.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) Files.ReadWrite, Files.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All
AnwendungApplication Sites.ReadWrite.AllSites.ReadWrite.All

Erstellen einer UploadsitzungCreate an upload session

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.To begin a large file upload, your app must first request a new upload session. This creates a temporary storage location where the bytes of the file will be saved until the complete file is uploaded. Once the last byte of the file has been uploaded the upload session is completed and the final file is shown in the destination folder.

HTTP-AnforderungHTTP request

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

AnforderungstextRequest body

Es ist kein Anforderungstexts erforderlich.No request body is required. Allerdings können Sie eine item-Eigenschaft im Anforderungstext definieren, um zusätzliche Daten zu der hochzuladenden Datei anzugeben.However, you can specify an item property in the request body, providing additional data about the file being uploaded.

{
  "@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.For example, to control the behavior if the filename is already taken, you can specify the conflict behavior property in the body of the request.

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

Optionale AnforderungsheaderOptional request headers

NameName WertValue BeschreibungDescription
if-matchif-match etagetag 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.If this request header is included and the eTag (or cTag) provided does not match the current etag on the item, a 412 Precondition Failed error response is returned.

EigenschaftenProperties

EigenschaftProperty TypType BeschreibungDescription
descriptiondescription ZeichenfolgeString Stellt eine für den Benutzer sichtbare Beschreibung des Elements bereit. Lese-/Schreibzugriff. Nur auf OneDrive PersonalProvides a user-visible description of the item. Read-write. Only on OneDrive Personal
fileSystemInfofileSystemInfo fileSystemInfofileSystemInfo Informationen zum Dateisystem des Clients. Lese-/Schreibzugriff.File system information on client. Read-write.
namename StringString Der Name des Elements (Dateiname und Erweiterung). Lese-/Schreibzugriff.The name of the item (filename and extension). Read-write.

AnforderungRequest

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.The response to this request will provide the details of the newly created uploadSession, which includes the URL used for uploading the parts of the file.

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

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

AntwortResponse

Wenn der Vorgang erfolgreich war, liefert die Antwort auf diese Anforderung die Details dazu, wohin die verbleibenden Anforderungen als UploadSession-Ressource gesendet werden sollen.The response to this request, if successful, will provide the details for where the remainder of the requests should be sent as an UploadSession resource.

Diese Ressource gibt Details zu dem Ort an, an dem der Bytebereich hochgeladen werden sollte und wann die Uploadsitzung abläuft.This resource provides details about where the byte range of the file should be uploaded and when the upload session expires.

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 UploadsitzungUpload bytes to the upload session

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.To upload the file, or a portion of the file, your app makes a PUT request to the uploadUrl value received in the createUploadSession response. Sie können die gesamte Datei hochladen oder die Datei in Fragmente aufteilen, vorausgesetzt, die maximale Bytezahl pro Anforderung bleibt unter 60 MiB.You can upload the entire file, or split the file into multiple byte ranges, as long as the maximum bytes in any given request is less than 60 MiB.

Die Dateifragmente müssen sequenziell in der richtigen Reihenfolge hochgeladen werden.The fragments of the file must be uploaded sequentially in order. Werden die Fragmente in der falschen Reihenfolge hochgeladen, tritt ein Fehler auf.Uploading fragments out of order will result in an error.

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.Note: If your app splits a file into multiple byte ranges, the size of each byte range MUST be a multiple of 320 KiB (327,680 bytes). Bei Fragmentgrößen, die sich nicht ohne Rest durch 320 KiB teilen lassen, treten beim Übergeben einiger Dateien Fehler auf.Using a fragment size that does not divide evenly by 320 KiB will result in errors committing some files.

BeispielExample

In diesem Beispiel lädt die App die ersten 26 Byte einer 128-Byte-Datei hoch.In this example, the app is uploading the first 26 bytes of a 128 byte file.

  • Der Header Content-Length definiert die Größe der aktuellen Anforderung.The Content-Length header specifies the size of the current request.
  • Der Header Content-Range gibt den Bytebereich in der Gesamtdatei an, den diese Anforderung repräsentiert.The Content-Range header indicates the range of bytes in the overall file that this request represents.
  • Die Gesamtlänge der Datei muss bekannt sein, bevor Sie das erste Fragment der Datei hochladen können.The total length of the file is known before you can upload the first fragment of the file.
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.Important: Your app must ensure the total file size specified in the Content-Range header is the same for all requests. Wird für einen Bytebereich eine andere Dateigröße deklariert, schlägt die betreffende Anforderung fehl.If a byte range declares a different file size, the request will fail.

AntwortResponse

Wenn die Anforderung abgeschlossen ist, antwortet der Server mit 202 Accepted, wenn es weitere Bytebereiche, die hochgeladen werden müssen.When the request is complete, the server will respond with 202 Accepted if there are more byte ranges that need to be uploaded.

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.Your app can use the nextExpectedRanges value to determine where to start the next byte range. Eventuell werden mehrere Bereiche angegeben. Sie stehen für Teile der Datei, die der Server noch nicht empfangen hat.You may see multiple ranges specified, indicating parts of the file that the server has not yet received. Dies ist nützlich, wenn eine Übertragung nach einer Unterbrechung fortgesetzt werden soll und der Client den Dienststatus nicht kennt.This is useful if you need to resume a transfer that was interrupted and your client is unsure of the state on the service.

Halten Sie sich bei der Festlegung der Größe der Bytebereiche immer an die unten beschriebenen bewährten Methoden.You should always determine the size of your byte ranges according to the best practices below. Gehen Sie nicht davon aus, dass nextExpectedRanges richtig dimensionierte Bytebereiche für einen Upload zurückgibt.Do not assume that nextExpectedRanges will return reanges of proper size for a byte range to upload. Die Eigenschaft nextExpectedRanges gibt Dateibereiche an, die noch nicht empfangen wurden. Sie ist nicht als Muster für den Dateiupload der App zu verstehen.The nextExpectedRanges property indicates ranges of the file that have not been received and not a pattern for how your app should upload the file.

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

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

HinweiseRemarks

  • Die Eigenschaft nextExpectedRanges listet nicht immer alle fehlenden Bereiche auf.The nextExpectedRanges property won't always list all of the missing ranges.
  • Wird ein Segment geschrieben, gibt sie den nächsten Bereich zurück, ab dem begonnen wird (z. B. „523-“).On successful fragment writes, it will return the next range to start from (eg. "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.On failures when the client sent a fragment the server had already received, the server will respond with HTTP 416 Requested Range Not Satisfiable. You can request upload status to get a more detailed list of missing ranges.
  • 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.Including the Authorization header when issuing the PUT call may result in a HTTP 401 Unauthorized response. The Authorization header and bearer token should only be sent when issuing the POST during the first step. It should be not be included when issueing the PUT.

Vervollständigen einer DateiCompleting a file

Sobald der Server den letzten Bytebereich einer Datei empfängt, antwortet er mit HTTP 201 Created oder HTTP 200 OK.When the last byte range of a file is received the server will response with an HTTP 201 Created or HTTP 200 OK. Der Antworttext enthält auch die Standardeigenschaft, die für das DriveItem festgelegt wurde, das die vervollständigte Datei repräsentiert.The response body will also include the default property set for the driveItem representing the completed file.

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-KonfliktenHandling upload conflicts

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.If a conflict occurs after the file is uploaded (for example, an item with the same name was created during the upload session), an error is returned when the last byte range is uploaded.

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 UploadsitzungCancel the upload session

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.To cancel an upload session send a DELETE request to the upload URL. This cleans up the temporary file holding the data previously uploaded. This should be used in scenarios where the upload is aborted, for example, if the user cancels the transfer.

Temporäre Dateien und die zugehörigen Uploadsitzungen werden automatisch bereinigt, wenn der über expirationDateTime festgelegte Termin abgelaufen ist.Temporary files and their accompanying upload session are automatically cleaned up after the expirationDateTime has passed. Temporäre Dateien werden eventuell nicht sofort gelöscht, nachdem die Ablaufzeit verstrichen ist.Temporary files may not be deleted immedately after the expiration time has elapsed.

AnforderungRequest

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

AntwortResponse

Das folgende Beispiel zeigt die Antwort.The following example shows the response.

HTTP/1.1 204 No Content

Fortsetzen eines laufenden UploadsResuming an in-progress upload

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.If an upload request is disconnected or fails before the request is completed, all bytes in that request are ignored. This can occur if the connection between your app and the service is dropped. If this occurs, your app can still resume the file transfer from the previously completed fragment.

Um herauszufinden, welche Bytebereiche bereits empfangen wurden, kann die App den Status der Uploadsitzung anfordern.To find out which byte ranges have been received previously, your app can request the status of an upload session.

BeispielExample

Sie können den Status des Uploads anfragen, indem Sie eine GET-Anforderung an uploadUrl senden.Query the status of the upload by sending a GET request to the uploadUrl.

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.The server will respond with a list of missing byte ranges that need to be uploaded and the expiration time for the upload session.

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

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

Hochladen von verbleibenden DatenUpload remaining data

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.Now that your app knows where to start the upload from, resume the upload by following the steps in upload bytes to the upload session.

Behandeln von Fehlern beim UploadHandle upload errors

Wenn der letzte Bytebereich einer Datei hochgeladen wird, kann ein Fehler auftreten.When the last byte range of a file is uploaded, it is possible for an error to occur. Dies kann an einem Namenskonflikt liegen oder daran, dass eine Kontingenteinschränkung überschritten wurde.This can be due to a name conflict or quota limitation being exceeded. Die Uploadsitzung wird bis zur Ablaufzeit beibehalten. Dadurch kann Ihre App den Upload wiederherstellen, indem ein ausdrücklicher Commit der Uploadsitzung durchgeführt wird.The upload session will be preserved until the expiration time, which allows your app to recover the upload by explicitly committing the upload session.

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.To explicitly commit the upload session, your app must make a PUT request with a new driveItem resource that will be used when committing the upload session. Diese neue Anforderung sollte die Quelle der Fehler korrigieren, die den ursprünglichen Uploadfehler verursacht hat.This new request should correct the source of error that generated the original upload error.

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.To indicate that your app is committing an existing upload session, the PUT request must include the @microsoft.graph.sourceUrl property with the value of your upload session URL.

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.Note: You can use the @microsoft.graph.conflictBehavior and if-match headers as expected in this call.

HTTP-AntwortHTTP response

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.If the file can be committed using the new metadata, an HTTP 201 Created or HTTP 200 OK response will be returned with the Item metadata for the uploaded file.

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

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

Bewährte MethodenBest practices

  • Setzen Sie alle Uploads fort bzw. starten Sie alle Uploads neu, die wegen eines Verbindungsabbruchs oder einem 5xx-Fehler fehlschlagen, beispielsweise:Resume or retry uploads that fail due to connection interruptions or any 5xx errors, including:
    • 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.Use an exponential back off strategy if any 5xx server errors are returned when resuming or retrying upload requests.
  • Bei anderen Fehlern sollten Sie keinen Exponential Backoff-Algorithmus verwenden, sondern stattdessen die Anzahl der Wiederholungsversuche beschränken.For other errors, you should not use an exponential back off strategy but limit the number of retry attempts made.
  • Sollte bei fortsetzbaren Uploads der Fehler 404 Not Found auftreten, starten Sie den gesamten Upload neu.Handle 404 Not Found errors when doing resumable uploads by starting the entire upload over. Dies bedeutet, dass die Upload-Sitzung nicht mehr vorhanden ist.This indicates the upload session no longer exists.
  • Verwenden Sie fortsetzbare Dateiübertragungen für Dateien, die größer als 10 MiB sind (10.485.760 Byte).Use resumable file transfers for files larger than 10 MiB (10,485,760 bytes).
  • Die optimale Größe eines Bytebereichs für stabile Highspeedverbindungen ist 10 MiB.A byte range size of 10 MiB for stable high speed connections is optimal. Bei langsameren oder weniger zuverlässigen Verbindungen liefern kleinere Fragmentgrößen eventuell bessere Ergebnisse.For slower or less reliable connections you may get better results from a smaller fragment size. Die empfohlene Fragmentgröße liegt zwischen 5 und 10 MiB.The recommended fragment size is between 5-10 MiB.
  • Verwenden Sie eine Bytebereichsgröße, die ein Vielfaches von 320 KiB ist (327.680 Byte) ist.Use a byte range size that is a multiple of 320 KiB (327,680 bytes). 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.Failing to use a fragment size that is a multiple of 320 KiB can result in large file transfers failing after the last byte range is uploaded.

FehlerantwortenError responses

Weitere Informationen dazu, wie Fehler zurückgegeben werden, finden Sie unter Fehlerantworten.See the Error Responses topic for details about how errors are returned.