driveItem: createUploadSession

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

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

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

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

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

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

Разрешения

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

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

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

HTTP-запрос

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

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

POST /drives/{driveId}/items/{parentItemId}:/{fileName}:/createUploadSession
POST /groups/{groupId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /users/{userId}/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 /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

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

Тело запроса

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

Например, свойство item позволяет задать следующие параметры:

{
  "@microsoft.graph.conflictBehavior": "fail (default) | replace | rename",
  "description": "description", // only available for OneDrive (personal)
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234, // only available for OneDrive (personal)
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

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

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

Запрос

Ответ на этот запрос содержит сведения о созданном методе 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 .

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

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

• Необходимо отправить следующий фрагмент или зафиксировать сеанс до времени, указанного в свойстве expirationDateTime .
• Каждый отправленный фрагмент продлевает срок действия, что позволяет успешно завершить отправку больших файлов. Обновленное время окончания срока действия возвращается при каждом запросе на отправку фрагмента файла.
• Если фрагменты не получены и сеанс не зафиксирован, все ранее отправленные фрагменты удаляются.

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

fileSize Если параметр указан и превышает доступную 507 Insufficient 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>

Отклик

По завершении запроса сервер отвечает 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 значение или не задан, отправка автоматически завершается, когда последний диапазон байтов файла помещается в 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>

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

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

Отклик

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

HTTP/1.1 204 No Content

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

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

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

Пример

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

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

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

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 с метаданными driveItem для отправленного файла.

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

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

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

• Возобновляйте или повторно запускайте операции отправки, не выполненные из-за разрывов соединения или каких-либо ошибок с кодом 5xx, в том числе:
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout
• Используйте стратегию экспоненциального откладывания, если при возобновлении или повторной отправке возвращаются ошибки сервера с кодом 5xx.
• Для других ошибок не следует использовать стратегию экспоненциального отката, но ограничить количество повторных попыток.
• Для устранения ошибок 404 Not Found при возобновляемой отправке начинайте всю отправку заново. Это означает, что сеанс отправки больше не существует.
• Используйте возобновляемую отправку для файлов размером более 10 МБ (10 485 760 байтов).
• Размер 10 МБ для диапазона байтов оптимален при использовании стабильных высокоскоростных подключений. Если используется более медленное или менее надежное подключение, то вы можете достичь оптимальных результатов, используя фрагменты меньших размеров. Рекомендуем использовать фрагменты размером 5–10 МиБ.
• Используйте размер фрагментов, кратный 320 КиБ (327 680 байтов). В противном случае после отправки последнего диапазона байтов большого файла может произойти сбой.

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

Подробнее о том, как возвращаются ошибки, см. в статье Возвращение ошибок.

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

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