命名空间：microsoft.graph
通过创建上传会话，使应用可以上传最大大小的文件。
上传会话允许应用在顺序 API 请求中上传文件的范围。 如果在上传过程中连接断开，则上传会话还允许继续传输。
若要使用上传会话上传文件，请执行以下作：
创建上载会话
将字节上传到上传会话
此 API 可用于以下
国家级云部署
。
美国政府 L4
美国政府 L5 (DOD)
由世纪互联运营的中国
SharePoint Embedded 需要
FileStorageContainer.Selected
权限才能访问容器的内容。 此权限不同于前面提到的权限。 除了Microsoft Graph 权限外，应用还必须具有调用此 API 所需的
容器类型权限
。 有关详细信息，请参阅
SharePoint Embedded 身份验证和授权
。
创建上传会话
要开始上载大文件，你的应用程序必须先请求新的上载会话。
此请求创建一个临时存储位置，在该位置保存文件的字节数，直到上传完整文件为止。
上传文件的最后一个字节时，上传会话已完成，最终文件显示在目标文件夹中。
或者，可以通过在请求参数中设置
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
"@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
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 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 错误而失败的上载，包括：
