Отправка больших файлов с помощью сеанса отправкиUpload large files with an upload session

Создайте сеанс отправки, чтобы приложение могло отправлять файлы, размер которых не превышает максимальный. С помощью сеанса отправки приложение может отправлять диапазоны файла при последовательных запросах API, что позволяет возобновить передачу, если во время отправки соединение будет разорвано.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.

Процесс отправки файла с помощью сеанса отправки состоит из двух этапов:To upload a file using an upload session, there are two steps:

  1. Создание сеанса отправки.Create an upload session
  2. Отправка байтов в сеанс отправки.Upload bytes to the upload session

РазрешенияPermissions

Для вызова этого API требуется одно из указанных ниже разрешений. Дополнительные сведения, включая сведения о том, как выбрать разрешения, см. в статье Разрешения.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Тип разрешенияPermission type Разрешения (в порядке повышения привилегий)Permissions (from least to most privileged)
Делегированные (рабочая или учебная учетная запись)Delegated (work or school account) Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)Delegated (personal Microsoft account) Files.ReadWrite, Files.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All
Для приложенийApplication Sites.ReadWrite.AllSites.ReadWrite.All

Создание сеанса отправкиCreate an upload session

Чтобы начать отправку большого файла, приложение должно сначала запросить новый сеанс отправки. При этом создается временное место хранения, где сохраняются байты файла, пока он не будет отправлен полностью. После отправки последнего байта файла сеанс отправки завершается, а готовый файл отображается в целевой папке.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-запросHTTP 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

Текст запросаRequest body

Тело запроса не требуется.No request body is required. Тем не менее, можно указать item свойство в тексте запроса, предоставляя дополнительные данные о выгружаемого файла.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"
}

Например, вы можете задать необходимые действия для случая, когда имя файла уже используется, указав в теле запроса свойство поведения при конфликтах.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"
  }
}

Необязательные заголовки запросовOptional request headers

ИмяName ЗначениеValue ОписаниеDescription
if-matchif-match etagetag Если указан заголовок запроса, а предоставленное значение eTag (или cTag) не совпадает с текущим значением eTag элемента, то возвращается ошибка 412 Precondition Failed.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.

СвойстваProperties

СвойствоProperty ТипType ОписаниеDescription
descriptiondescription StringString Предоставляет видимое пользователю описание элемента. Чтение и запись. Только в личном хранилище OneDriveProvides a user-visible description of the item. Read-write. Only on OneDrive Personal
fileSystemInfofileSystemInfo fileSystemInfofileSystemInfo Сведения о файловой системе на клиенте. Чтение и запись.File system information on client. Read-write.
namename StringString Имя элемента (имя и расширение файла). Чтение и запись.The name of the item (filename and extension). Read-write.

ЗапросRequest

В отклике на этот запрос будут представлены подробные сведения о новом экземпляре uploadSession (в том числе 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"
  }
}

ОткликResponse

В случае успешного выполнения запроса ответ будет содержать сведения о том, куда отправлять остальные запросы (в виде ресурса UploadSession).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.

Этот ресурс предоставляет сведения о том, куда следует отправлять диапазон байтов файла и когда истекает срок действия сеанса отправки.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"
}

Отправка байтов в сеанс отправкиUpload bytes to the upload session

Чтобы отправить файл или его часть, приложение выполняет запрос PUT на адрес uploadUrl, указанный в отклике для createUploadSession.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. Вы можете отправить файл целиком или разделить его на несколько диапазонов байтов. При этом каждый запрос должен содержать фрагмент размером не более 60 МБ.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.

Фрагменты файл должен загружаться последовательно в порядке.The fragments of the file must be uploaded sequentially in order. В противном случае возникнет ошибка.Uploading fragments out of order will result in an error.

Примечание. Если приложение делит файл на несколько диапазонов байтов, размер каждого из них ДОЛЖЕН быть кратным 320 КБ (327 680 байтов).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). Если размер фрагментов не делится на 320 КБ без остатка, при отправке некоторых файлов возникнут ошибки.Using a fragment size that does not divide evenly by 320 KiB will result in errors committing some files.

ПримерExample

В этом примере приложение отправляет первые 26 из 128 байтов файла.In this example, the app is uploading the first 26 bytes of a 128 byte file.

  • Заголовок Content-Length задает размер текущего запроса.The Content-Length header specifies the size of the current request.
  • Заголовок Content-Range указывает диапазон (в байтах) для всего файла, представленного в запросе.The Content-Range header indicates the range of bytes in the overall file that this request represents.
  • Прежде чем отправлять первый фрагмент файла, необходимо знать общий размер этого файла.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>

Важно! Приложение должно указывать в заголовках Content-Range всех запросов один и тот же общий размер файла.Important: Your app must ensure the total file size specified in the Content-Range header is the same for all requests. Если объявить для диапазона байтов другой размер файла, запрос не будет выполнен.If a byte range declares a different file size, the request will fail.

ОткликResponse

После выполнения запроса сервер отправит в ответ код 202 Accepted, если требуется отправить дополнительные диапазоны байтов.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-"]
}

С помощью значения nextExpectedRanges приложение может определить, где должен начинаться следующий диапазон байтов.Your app can use the nextExpectedRanges value to determine where to start the next byte range. Вы можете увидеть несколько диапазонов, указывающих части файла, еще не полученные сервером.You may see multiple ranges specified, indicating parts of the file that the server has not yet received. Это удобно, когда требуется возобновить прерванную передачу, а клиенту неизвестно состояние службы.This is useful if you need to resume a transfer that was interrupted and your client is unsure of the state on the service.

Размер диапазонов байтов всегда следует определять в соответствии с приведенными ниже рекомендациями.You should always determine the size of your byte ranges according to the best practices below. Не предполагайте, что этот nextExpectedRanges возвращает диапазоны соответствующего размера для диапазона байтов для загрузки.Do not assume that nextExpectedRanges will return ranges of proper size for a byte range to upload. Свойство nextExpectedRanges указывает диапазоны файла, которые не были получены, а не схему отправки файла приложением.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"
  ]
}

ЗамечанияRemarks

  • В свойстве nextExpectedRanges не всегда указываются все отсутствующие диапазоны.The nextExpectedRanges property won't always list all of the missing ranges.
  • При успешной записи фрагментов оно возвращает следующий диапазон (например, "523-").On successful fragment writes, it will return the next range to start from (eg. "523-").
  • При сбоях в тех случаях, когда клиент отправляет файл, уже полученный сервером, сервер возвращает отклик HTTP 416 Requested Range Not Satisfiable. Вы можете запросить состояние отправки, чтобы получить более подробный список недостающих диапазонов.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.
  • Как отклик на добавление заголовка авторизации при совершении вызова PUT может появиться сообщение об ошибке HTTP 401 Unauthorized. Заголовок авторизации и токен носителя необходимо отправлять только при выполнении POST на начальном этапе. Не следует включать их, когда совершается вызов PUT.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.

Завершение отправки файлаCompleting a file

После получения последнего диапазона байтов файла сервер отправляет отклик HTTP 201 Created или 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. Тело отклика также включает набор свойств по умолчанию для ресурса driveItem, представляющего полностью отправленный файл.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": { }
}

Обработка конфликтов при отправкеHandling upload conflicts

В случае возникновения конфликта после отправки файла (например, если в ходе сеанса отправки был создан элемент с таким же именем) при отправке последнего диапазона байтов возвращается ошибка.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.",
  }
}

Отмена сеанса отправкиCancel the upload session

Чтобы отменить сеанс отправки, отправьте запрос DELETE на URL-адрес отправки. При этом очищается временный файл, содержащий ранее отправленные данные. Это следует делать в тех случаях, когда отправка прерывается (например, если пользователь отменил передачу).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.

Временные файлы и соответствующий сеанс отправки автоматически очищаются по прошествии времени, указанного свойством expirationDateTime.Temporary files and their accompanying upload session are automatically cleaned up after the expirationDateTime has passed. Временные файлы могут быть удалены не сразу по истечении срока действия.Temporary files may not be deleted immedately after the expiration time has elapsed.

ЗапросRequest

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

ОткликResponse

Ниже приводится пример отклика.The following example shows the response.

HTTP/1.1 204 No Content

Возобновление выполняемой отправкиResuming an in-progress upload

При отключении или сбое отправки до полного выполнения запроса все байты в этом запросе игнорируются. Это может произойти при разрыве соединения между приложением и службой. В этом случае приложение может возобновить передачу файла с ранее отправленного фрагмента.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.

Чтобы узнать, какие диапазоны байтов были получены ранее, приложение может запросить состояние сеанса отправки.To find out which byte ranges have been received previously, your app can request the status of an upload session.

ПримерExample

Получить состояние отправки можно, отправив запрос GET на адрес uploadUrl.Query the status of the upload by sending a GET request to the uploadUrl.

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

В ответ сервер отправит список отсутствующих байтовых диапазонов, которые требуется отправить, и время окончания срока действия для сеанса отправки.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-"]
}

Отправка оставшихся данныхUpload remaining data

Теперь, когда приложению известно, с какого момента начинать отправку, возобновите операцию, выполнив действия из раздела Отправка байтов в сеанс отправки.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.

Обработка ошибок отправкиHandle upload errors

После отправки последнего диапазона байтов файла может возникнуть ошибка.When the last byte range of a file is uploaded, it is possible for an error to occur. Она может быть вызвана конфликтом имен или превышением ограничения квоты.This can be due to a name conflict or quota limitation being exceeded. Сеанс отправки будет сохранен до истечения срока его действия. Это позволяет приложению возобновить отправку, явно зафиксировав сеанс отправки.The upload session will be preserved until the expiration time, which allows your app to recover the upload by explicitly committing the upload session.

Для этого приложение должно отправить запрос PUT с новым ресурсом driveItem, который будет использоваться при фиксации сеанса отправки.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. Этот новый запрос должен устранить причину первоначальной ошибки отправки.This new request should correct the source of error that generated the original upload error.

Чтобы указать, что приложение применяет существующий сеанс отправки, запрос PUT должен включать свойство @microsoft.graph.sourceUrl со значением URL-адреса сеанса отправки.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}"
}

Примечание. В этом вызове можно использовать заголовки @microsoft.graph.conflictBehavior и if-match надлежащим образом.Note: You can use the @microsoft.graph.conflictBehavior and if-match headers as expected in this call.

HTTP-откликHTTP response

Если файл можно зафиксировать с помощью новых метаданных, возвращается ответ HTTP 201 Created или HTTP 200 OK с метаданными ресурса Item для отправленного файла.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": { }
}

РекомендацииBest practices

  • Возобновляйте или повторно запускайте операции отправки, не выполненные из-за разрывов соединения или каких-либо ошибок с кодом 5xx, в том числе: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
  • Используйте стратегию экспоненциального откладывания, если при возобновлении или повторной отправке возвращаются ошибки сервера с кодом 5xx.Use an exponential back off strategy if any 5xx server errors are returned when resuming or retrying upload requests.
  • При возникновении других ошибок не следует использовать эту стратегию. Вместо этого ограничьте количество повторных попыток.For other errors, you should not use an exponential back off strategy but limit the number of retry attempts made.
  • Для устранения ошибок 404 Not Found при возобновляемой отправке начинайте всю отправку заново.Handle 404 Not Found errors when doing resumable uploads by starting the entire upload over. Это означает, что сеанс отправки больше не существует.This indicates the upload session no longer exists.
  • Используйте возобновляемую отправку для файлов размером более 10 МБ (10 485 760 байтов).Use resumable file transfers for files larger than 10 MiB (10,485,760 bytes).
  • Размер 10 МБ для диапазона байтов оптимален в случае стабильных высокоскоростных подключений.A byte range size of 10 MiB for stable high speed connections is optimal. Если используется более медленное или менее надежное подключение, то вы можете получить оптимальные результаты, используя фрагменты меньшего размера.For slower or less reliable connections you may get better results from a smaller fragment size. Рекомендуем использовать фрагменты размером 5–10 МБ.The recommended fragment size is between 5-10 MiB.
  • Используйте размер фрагментов, кратный 320 КБ (327 680 байтов).Use a byte range size that is a multiple of 320 KiB (327,680 bytes). В противном случае после отправки последнего диапазона байтов большого файла может произойти сбой.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.

Ответы с ошибкамиError responses

Дополнительные сведения о том как возвращаются ошибки, см. в статье Ошибки.See the Error Responses topic for details about how errors are returned.