driveItem: createUploadSession

Статья
10/07/2023

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

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

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

Чтобы отправить файл с помощью сеанса отправки:

Создание сеанса отправки.
Отправка байтов в сеанс отправки.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	✅	✅	✅

Разрешения

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

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

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

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

HTTP-запрос

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

Тело запроса

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

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

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

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

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  },
  "deferCommit": true
}

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

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

Параметры

Параметр	Тип	Описание
deferCommit	Boolean	Если задано значение `true`, для окончательного создания файла в назначении требуется явный запрос.
item	driveItemUploadableProperties	Сведения об отправляемом файле.

Запрос

Ответ на этот запрос содержит сведения о созданном методе uploadSession, который включает URL-адрес, используемый для отправки частей файла.

Примечание. {item-path} должен содержать имя элемента, указанного в тексте запроса.

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

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

Ответ

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

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

fileSize Если параметр указан и превышает доступную 507 Insufficent Storage квоту, возвращается ответ и сеанс отправки не будет создан.

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

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

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

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

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

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

Пример

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

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

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 26
Content-Range: bytes 0-25/128

<bytes 0-25 of the file>

Примечание.

Сведения о том, как отправлять большие файлы с помощью пакетов SDK, см . в статье Отправка больших файлов с помощью пакетов SDK Microsoft Graph.
Приложение должно убедиться, что общий размер файла, указанный в заголовке Content-Range , одинаков для всех запросов. Если объявить для диапазона байтов другой размер файла, запрос не будет выполнен.

Ответ

По завершении запроса сервер отвечает 202 Accepted , если необходимо отправить больше диапазонов байтов.

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

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

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

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

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

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

Примечания

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

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

Если параметр deferCommit имеет значение "false" или он не задан, то отправка автоматически завершается, когда последний диапазон байтов файла методом PUT достигает URL-адреса отправки.

Если параметр deferCommit имеет значение "true", то можно явным образом завершить отправку двумя способами:

После того как последний диапазон байтов файла методом PUT достигает URL-адреса отправки, отправьте последний запрос POST на URL-адрес отправки с содержимым нулевой длины (в настоящее время поддерживается только в OneDrive для бизнеса и в SharePoint).
После того как последний диапазон байтов файла методом PUT достигает URL-адреса отправки, отправьте последний запрос PUT таким же образом, которым вы бы обрабатывали ошибки отправки (в настоящее время поддерживается только в OneDrive персональный).

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

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

<final bytes of the file>

Примечание.

Сведения о том, как отправлять большие файлы с помощью пакетов SDK, см . в статье Отправка больших файлов с помощью пакетов SDK Microsoft Graph.

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

Примечание.

Сведения о том, как отправлять большие файлы с помощью пакетов SDK, см . в статье Отправка больших файлов с помощью пакетов SDK Microsoft Graph.

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

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

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

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

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

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

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

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

Запрос

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

Примечание.

Сведения о том, как отправлять большие файлы с помощью пакетов SDK, см . в статье Отправка больших файлов с помощью пакетов SDK Microsoft Graph.

Отклик

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

HTTP/1.1 204 No Content

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

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

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

Пример

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

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

Примечание.

Сведения о том, как отправлять большие файлы с помощью пакетов SDK, см . в статье Отправка больших файлов с помощью пакетов SDK Microsoft Graph.

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

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

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

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

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

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

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

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

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

PUT https://graph.microsoft.com/beta/me/drive/root:/{path_to_file}
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 надлежащим образом.

Ответ

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

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

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

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

Дополнительные сведения о возвращении ошибок см. в статье Ответы с ошибками.

Отправка большого файла

driveItem: createUploadSession

Разрешения

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

HTTP-запрос

Тело запроса

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

Параметры

Запрос

Ответ

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

Пример

Ответ

Примечания

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

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

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

Запрос

Отклик

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

Пример

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

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

Ответ

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

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

Обратная связь

Обратная связь

Дополнительные ресурсы

driveItem: createUploadSession

Разрешения

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

HTTP-запрос

Тело запроса

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

Параметры

Запрос

Ответ

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

Пример

Ответ

Примечания

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

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

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

Запрос

Отклик

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

Пример

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

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

Ответ

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

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

Связанные материалы

Обратная связь

Обратная связь

Дополнительные ресурсы