driveItem：createUploadSession
命名空间：microsoft.graph
通过创建上传会话，使应用可以上传最大大小的文件。 上传会话允许应用在顺序 API 请求中上传文件的范围。 如果在上传过程中连接断开，则上传会话还允许继续传输。
若要使用上传会话上传文件，请执行以下操作：
此 API 可用于以下国家级云部署。
| 全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
权限
为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。
| 权限类型 | 最低特权权限 | 更高特权权限 |
|---|---|---|
| 委派（工作或学校帐户） | Files.ReadWrite | Files.ReadWrite.All、Sites.ReadWrite.All |
| 委派（个人 Microsoft 帐户） | Files.ReadWrite | Files.ReadWrite.All |
| 应用程序 | Sites.ReadWrite.All | 不可用。 |
创建上传会话
要开始上载大文件，你的应用程序必须先请求新的上载会话。 此请求创建一个临时存储位置，在该位置保存文件的字节数，直到上传完整文件为止。 上传文件的最后一个字节时，上传会话已完成，最终文件显示在目标文件夹中。 或者，可以通过在请求参数中设置 deferCommit 属性，延迟目标中文件的最终创建，直到显式发出完成上传的请求。
HTTP 请求
若要上传新文件，必须在请求中同时提供父 ID 和新文件名。 但是，更新仅需要将更新的项的 ID。
创建新文件
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 | 布尔值 | 如果设置为 true，则最终在目标中创建文件需要显式请求。 |
| 项 | 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"
}
将字节上传到上传会话
若要上传文件或文件的一部分，你的应用可以对在 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时，仅发送授权标头和持有者令牌。 发出PUT呼叫时不要包含它。
完成文件
如果 deferCommit 为 false 或未设置，则在将文件的最终字节范围放入上传 URL 时，将自动完成上传。
如果 deferCommit 为 true，则可通过以下两种方式显式完成上传：
- 将文件的最终字节范围放入上传 URL 后，将最终的 POST 请求发送到内容长度为零的上传 URL（当前仅在 OneDrive for Business 和 SharePoint 中受支持）。
- 将文件的最终字节范围放入上传 URL 后，以处理上传错误的相同方式发送最终 PUT 请求（目前仅在 OneDrive Personal 中受支持）。
上传完成后，服务器使用 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 上传大型文件，请参阅 使用 Microsoft Graph SDK 上传大型文件。
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 上传大型文件，请参阅 使用 Microsoft Graph SDK 上传大型文件。
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.",
}
}
取消上传会话
若要取消上载会话，请向上载 UR L 发送 DELETE 请求。 这会清理用来保留以前上载的数据的临时文件。 应在上载中止（例如，如果用户取消传输）的情况下使用上述方法。
expirationDateTime 通过后，系统将自动清理临时文件及其随附的上载会话。 过期时间过后可能不会立即删除临时文件。
请求
DELETE https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
注意
- 若要使用 SDK 上传大型文件，请参阅 使用 Microsoft Graph SDK 上传大型文件。
响应
以下示例显示了相应的响应。
HTTP/1.1 204 No Content
继续正在进行的上传
如果上载请求在完成前断开或失败，将忽略该请求中的所有字节。 如果应用程序与服务之间的连接断开，可能会发生这种情况。 如果发生这种情况，应用程序仍可以继续传输以前完成的文件片段。
若要查找以前已接收的字节范围，应用程序可以请求上载会话的状态。
示例
通过向 uploadUrl 发送 GET 请求来查询上载状态。
GET https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF86633784148bb98a1zjcUhf7b0mpUadahs
服务器使用需要上传的缺失字节范围列表以及上传会话的过期时间进行响应。
注意
- 若要使用 SDK 上传大型文件，请参阅 使用 Microsoft Graph SDK 上传大型文件。
HTTP/1.1 200 OK
Content-Type: application/json
{
"expirationDateTime": "2015-01-29T09:21:55.523Z",
"nextExpectedRanges": ["12345-"]
}
上载剩余数据
现在，你的应用程序已经知道开始上载的位置，请按照 将字节上载到上载会话 中的步骤继续上载。
处理上传错误
上传文件的最后一个字节范围时，可能会出现错误。 这可能是由于名称冲突或超出配额限制所致。 上传会话将一直保留到到期时间，这使应用可以通过显式提交上传会话来恢复上传。
若要显式提交上传会话，应用必须使用将用来提交上传会话的新 driveItem 资源发出 PUT 请求。 此新请求应纠正生成原始上传错误的错误根源。
若要指示应用提交现有上传会话，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 响应，其中包含已上传文件的 Item 元数据。
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "912310013A123",
"name": "largefile.vhd",
"size": 128,
"file": { }
}
最佳做法
- 继续或重试由于连接中断或任意 5xx 错误而失败的上载，包括：
500 Internal Server Error502 Bad Gateway503 Service Unavailable504 Gateway Timeout
- 如果在继续或重试上载请求时返回任意 5xx 服务器错误，请使用指数退避战略。
- 对于其他错误，不应使用指数退避策略，而应限制重试次数。
- 通过重新开始整个上传继续上传时，请处理
404 Not Found错误。 这表示上传会话不再存在。 - 对大于 10 MiB（10,485,760 个字节）的文件使用可恢复文件传输。
- 最佳的字节范围大小是 10 MiB，可以实现稳定高速连接。 对于较慢或不太可靠的连接，可能会从较小的片段大小获得更好的结果。 建议使用的片段大小为 5-10 MiB 之间。
- 使用 320 KiB（327,680 个字节）倍数的字节范围大小。 如果使用的片段大小不是 320 KiB 的倍数，可能会在上传最后一个字节范围后导致大文件传输失败。
错误响应
有关错误返回方式的详细信息，请参阅错误 响应 一文。
相关内容
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈