driveItem: createUploadSession

Статья
10/30/2023

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

Создайте сеанс отправки, чтобы приложение могло отправлять файлы, размер которых не превышает максимальный. Сеанс отправки позволяет приложению передавать диапазоны файла в последовательных запросах 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 /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession

Обновление существующего файла

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

Заголовки запросов

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

Тело запроса

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

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

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

Чтобы отменить сеанс отправки, отправьте запрос 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/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}"
}

Отклик

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

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

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

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

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

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

driveItem: createUploadSession

Разрешения

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

HTTP-запрос

Создание файла

Обновление существующего файла

Заголовки запросов

Тело запроса

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

Параметры

Запрос

Ответ

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

Пример

Ответ

Замечания

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

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

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

Запрос

Отклик

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

Пример

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

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

Отклик

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

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

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

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

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

driveItem: createUploadSession

Разрешения

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

HTTP-запрос

Создание файла

Обновление существующего файла

Заголовки запросов

Тело запроса

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

Параметры

Запрос

Ответ

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

Пример

Ответ

Замечания

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

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

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

Запрос

Отклик

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

Пример

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

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

Отклик

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

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

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

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

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

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