driveItem：createUploadSession

命名空间：microsoft.graph

通过创建上传会话，使应用可以上传最大大小的文件。

上传会话允许应用在顺序的 API 请求中上传文件范围。 如果在上传过程中断开连接，它还允许恢复传输。

使用上传会话上传文件：

  1. 创建上载会话
  2. 将字节上传到上传会话

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Files.ReadWrite Files.ReadWrite.All、Sites.ReadWrite.All
委派（个人 Microsoft 帐户） Files.ReadWrite Files.ReadWrite.All
应用程序 Sites.ReadWrite.All 不可用。

注意

仅应用身份验证不支持替换使用敏感度标签保护的文件的内容。 请改用委派权限 (用户上下文) 。

注意

SharePoint Embedded 需要访问 FileStorageContainer.Selected 容器内容的权限。 此权限与前面提到的权限不同。 除了 Microsoft Graph 权限外，应用还必须具有调用此 API 所需的 容器类型权限 。 有关详细信息，请参阅 SharePoint Embedded 身份验证和授权。

HTTP 请求

若要上传新文件，必须在请求中同时提供父 ID 和新文件名。 但是，更新只需要要更新的项目的 ID。

新建文件

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

请求标头

名称 值 说明
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", // 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
}
属性 类型 说明
deferCommit 布尔值 如果设置为 true，则在目标中最终创建文件需要显式请求。
项 driveItemUploadableProperties 有关正在上传的文件的数据。

响应

如果成功，对此请求的响应将提供有关应将请求的其余部分作为 uploadSession 资源发送到何处的详细信息。

创建会话并生成经过预身份验证的上传 URL 时，该上传 URL 可用于在足以容纳大型文件的时间范围内完成上传。

uploadSession 资源提供有关应将文件的每个字节范围上传到何处的详细信息，并指定会话何时过期。 expirationDateTime 属性指示当前会话在没有进一步活动发生时过期的时间。 这会导致以下行为：

  • 必须在 expirationDateTime 属性中指定的时间之前上传下一个片段或提交会话。
  • 每个上传的片段都会延长过期时间，从而成功完成大型文件上传。 每次请求上传文件片段时，都会返回更新后的过期时间。
  • 如果未收到任何片段且会话未提交，则将丢弃之前上传的所有片段。

此过程支持大文件上传，并通过防止过时或废弃的数据在系统中保留太久来确保有效管理上传会话。

如果指定参数并超过可用配额，则 fileSize 会返回响应， 507 Insufficient Storage 并且不会创建上传会话。

示例

示例 1：创建上传会话

要开始上载大文件，你的应用程序必须先请求新的上载会话。 此请求将创建一个临时存储位置，在文件字节保存到上传完整文件为止。 上传文件的最后一个字节后，上传会话完成，最终文件显示在目标文件夹中。 或者，可以通过在请求参数中设置 deferCommit 属性，将文件在目标中的最终创建推迟到显式请求完成上传为止。

请求

对此请求的响应提供新创建的 uploadSession 的详细信息，其中包括用于上传文件各部分的 URL。

注意：{item-path} 必须包含请求正文中指定的项的名称。

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

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

响应

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

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

示例 2： 将字节上传到上传会话

若要上传文件或文件的一部分，你的应用可以对在 createUploadSession 响应中收到的 uploadUrl 值创建 PUT 请求。 可以上传整个文件，也可以将文件拆分为多个字节范围，只要任意给定请求的最大字节数少于 60 MiB 即可。

必须按顺序上传文件的片段。 无序上传片段会导致错误。

注意：如果应用将一个文件拆分为多个字节范围，则每个字节范围的大小必须是 320 KiB（327,680 个字节）的倍数。

使用不能被 320 KiB 整除的片段大小会导致提交某些文件时出错。

请求

在此示例中，应用将上传 128 字节文件的前 26 字节。

  • 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 上传大型文件，请参阅 使用 Microsoft Graph SDK 上传大型文件。
  • 应用必须确保标头中 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 调用时包括 Authorization 标头，则可能会导致 HTTP 401 Unauthorized 响应。 在第一步中发出 POST 请求时，仅包含 Authorization 标头和持有者令牌。 发出 PUT 调用时请勿包括它。

示例 3：完成文件 (deferCommit 为 false)

如果 deferCommit 为 false 或未设置，则当文件的最后一个字节范围被 PUT 到上传 URL 时，上传会自动完成。

上传完成后，服务器会使用 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": { }
}

示例 4：完成文件 (deferCommit 为 false)

如果 deferCommit 为 true，则可以通过两种方式显式完成上传：

  • 将文件的最终字节范围放入上传 URL 后，将最终的 POST 请求发送到内容长度为零的上传 URL（当前仅在 OneDrive for Business 和 SharePoint 中受支持）。
  • 将文件的最终字节范围放入上传 URL 后，以处理上传错误的相同方式发送最终 PUT 请求（目前仅在 OneDrive Personal 中受支持）。

上传完成后，服务器会使用 HTTP 201 Created “或 HTTP 200 OK”响应最终请求。 响应正文还包括表示已完成文件的 driveItem 的默认属性集。

请求

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

示例 5：取消上传会话

若要取消上载会话，请向上载 UR L 发送 DELETE 请求。 这会清理用来保留以前上载的数据的临时文件。 应在上载中止（例如，如果用户取消传输）的情况下使用上述方法。

expirationDateTime 通过后，系统将自动清理临时文件及其随附的上载会话。 过期时间后可能不会立即删除临时文件。

请求

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

注意

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content

示例 6：恢复正在上传

如果上载请求在完成前断开或失败，将忽略该请求中的所有字节。 如果应用程序与服务之间的连接断开，可能会发生这种情况。 如果发生这种情况，应用程序仍可以继续传输以前完成的文件片段。

若要查找以前已接收的字节范围，应用程序可以请求上载会话的状态。

请求

通过向 uploadUrl 发送 GET 请求来查询上载状态。

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-"]
}

现在，你的应用程序已经知道开始上载的位置，请按照 将字节上载到上载会话 中的步骤继续上载。

示例 7：处理上传错误

上传文件的最后一个字节范围时，可能会发生错误。 这可能是由于名称冲突或超出配额限制所致。 上传会话将保留到过期时间，这使您的应用可以通过显式提交上传会话来恢复上传。

若要显式提交上传会话，你的应用必须发出 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}"
}

注意：可以在此调用中正常使用 @microsoft.graph.conflictBehavior 和 if-match 头。

响应

如果可以使用新的元数据提交文件，则将返回带有 HTTP 201 Created 已上传文件的项目元数据的 OR HTTP 200 OK 响应。

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 MiB（10,485,760 个字节）的文件使用可恢复文件传输。
  • 最佳的字节范围大小是 10 MiB，可以实现稳定高速连接。 对于速度较慢或不可靠的连接，较小的文件片段大小可能会给你带来更好的结果。 建议使用的片段大小为 5-10 MiB 之间。
  • 使用 320 KiB（327,680 个字节）倍数的字节范围大小。 如果使用的片段大小不是 320 KiB 的倍数，可能会在上传最后一个字节范围后导致大文件传输失败。

错误响应

如果在文件上传后发生冲突（例如，在上传会话期间创建了同名的项），则会在最后一个字节范围上传时返回错误。

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

有关如何返回错误的详细信息，请参阅 错误响应 文章。

相关内容

大文件上传

  • 上次更新时间为