Отправка больших файлов с помощью сеанса отправки

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

Процесс отправки файла с помощью сеанса отправки состоит из двух этапов:

Разрешения

Для вызова этого API требуется одно из указанных ниже разрешений. Дополнительные сведения, включая сведения о том, как выбрать разрешения, см. в статье Разрешения.

Тип разрешения Разрешения (в порядке повышения привилегий) Делегированные (рабочая или учебная учетная запись) Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All Делегированные (личная учетная запись Майкрософт) Files.ReadWrite, Files.ReadWrite.All Для приложений Sites.ReadWrite.All

Создание сеанса отправки

Чтобы начать отправку большого файла, приложение должно сначала запросить новый сеанс отправки. При этом создается временное место хранения, где сохраняются байты файла, пока он не будет отправлен полностью. Чтобы загрузить новый файл, укажите ID или путь к родительской папке. Чтобы обновить существующий файл, укажите ID или путь к обновляемому файлу. После отправки последнего байта файла сеанс отправки завершается, а готовый файл отображается в целевой папке.

HTTP-запрос Текст запроса

Тело запроса не обязательно. Но вы можете указать свойство item в теле запроса, чтобы предоставить дополнительные данные об отправляемом файле.

Например, вы можете задать необходимые действия для случая, когда имя файла уже используется, указав в теле запроса свойство поведения при конфликтах.

Необязательные заголовки запросов Имя Значение Описание if-match etag Если указан заголовок запроса, а предоставленное значение eTag (или cTag) не совпадает с текущим значением eTag элемента, то возвращается ошибка 412 Precondition Failed .

Свойства

Свойство Тип Описание description String Предоставляет видимое пользователю описание элемента. Чтение и запись. Только в личном хранилище OneDrive fileSystemInfo fileSystemInfo Сведения о файловой системе на клиенте. Чтение и запись. name String Имя элемента (имя и расширение файла). Чтение и запись. Запрос

В отклике на этот запрос будут представлены подробные сведения о новом экземпляре uploadSession (в том числе URL-адрес для отправки фрагментов файла).

Ответ

В случае успешного выполнения запроса ответ будет содержать сведения о том, куда отправлять остальные запросы (в виде ресурса UploadSession).

Этот ресурс предоставляет сведения о том, куда следует отправлять диапазон байтов файла и когда истекает срок действия сеанса отправки.

Отправка байтов в сеанс отправки

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

Фрагменты файла необходимо отправлять в правильном порядке. В противном случае возникнет ошибка.

Примечание. Если приложение делит файл на несколько диапазонов байтов, размер каждого из них ДОЛЖЕН быть кратным 320 КиБ (327 680 байт). Если размер фрагментов не делится на 320 КиБ без остатка, при отправке некоторых файлов произойдут ошибки.

Пример

В этом примере приложение отправляет первые 26 из 128 байтов файла.

Заголовок Content-Length задает размер текущего запроса.
Заголовок Content-Range указывает диапазон байтов для всего файла, представленного в запросе.
Прежде чем отправлять первый фрагмент файла, необходимо знать общий размер этого файла.

Важно! Приложение должно указывать в заголовках Content-Range всех запросов один и тот же общий размер файла. Если объявить для фрагмента другой диапазон байтов, запрос не будет выполнен.

Ответ

После выполнения запроса сервер отправит в ответ код 202 Accepted , если требуется отправить дополнительные диапазоны байтов.

С помощью значения nextExpectedRanges приложение может определить, где должен начинаться следующий диапазон байтов. Вы можете увидеть несколько диапазонов, указывающих части файла, еще не полученные сервером. Это удобно, когда требуется возобновить прерванную передачу, а клиенту неизвестно состояние службы.

Размер диапазонов байтов всегда следует определять в соответствии с приведенными ниже рекомендациями. Не рассчитывайте на то, что свойство nextExpectedRanges вернет диапазоны надлежащего размера для отправляемого диапазона байтов. Свойство nextExpectedRanges указывает диапазоны файла, которые не были получены, а не схему отправки файла.

Примечания

Свойство nextExpectedRanges не всегда указывает все отсутствующие диапазоны.
При успешной записи фрагментов оно возвращает следующий диапазон (например, "523-").
При сбоях в тех случаях, когда клиент отправляет файл, уже полученный сервером, сервер возвращает отклик HTTP 416 Requested Range Not Satisfiable . Вы можете запросить состояние отправки, чтобы получить более подробный список недостающих диапазонов.
Как отклик на добавление заголовка авторизации при совершении вызова PUT может появиться сообщение об ошибке HTTP 401 Unauthorized . Заголовок авторизации и токен носителя необходимо отправлять только при выполнении POST на начальном этапе. Не следует включать их, когда совершается вызов PUT .

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

После получения последнего диапазона байтов сервер отправляет отклик HTTP 201 Created или HTTP 200 OK . Тело отклика также включает набор свойств по умолчанию для ресурса driveItem, представляющего полностью отправленный файл.

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

В случае возникновения конфликта после отправки файла (например, если в ходе сеанса отправки был создан элемент с таким же именем) при отправке последнего диапазона байтов возвращается ошибка.

Отмена сеанса отправки

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

Временные файлы и соответствующий сеанс отправки автоматически очищаются по прошествии времени, указанного свойством expirationDateTime. Временные файлы могут быть удалены не сразу по истечении срока действия.

Запрос Отклик

Ниже приводится пример отклика.

Возобновление выполняемой отправки

При отключении или сбое отправки до полного выполнения запроса все байты в этом запросе игнорируются. Это может произойти при разрыве соединения между приложением и службой. В этом случае приложение может возобновить передачу файла с ранее отправленного фрагмента.

Чтобы узнать, какие диапазоны байтов были получены ранее, приложение может запросить состояние сеанса отправки.

Пример

Получить состояние отправки можно, отправив запрос GET на адрес uploadUrl .

В ответ сервер отправит список отсутствующих байтовых диапазонов, которые требуется отправить, и время окончания срока действия для сеанса отправки.

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

Теперь, когда приложению известно, с какого момента начинать отправку, возобновите операцию, выполнив действия из раздела Отправка байтов в сеанс отправки.

Обработка ошибок отправки

После отправки последнего диапазона байтов файла может возникнуть ошибка. Она может быть вызвана конфликтом имен или превышением ограничения квоты. Сеанс отправки будет сохранен до истечения срока его действия. Это позволяет приложению возобновить отправку, явно зафиксировав сеанс отправки.

Для этого приложение должно отправить запрос PUT с новым ресурсом driveItem, который будет использоваться при фиксации сеанса отправки. Этот новый запрос должен устранить причину первоначальной ошибки отправки.

Чтобы указать, что приложение применяет существующий сеанс отправки, запрос PUT должен включать свойство @microsoft.graph.sourceUrl со значением URL-адреса сеанса отправки.

Примечание. В этом вызове можно использовать заголовки @microsoft.graph.conflictBehavior и if-match надлежащим образом.

HTTP-ответ

Если файл можно зафиксировать с помощью новых метаданных, возвращается ответ HTTP 201 Created или HTTP 200 OK с метаданными ресурса Item для отправленного файла.