将文件附加到待办事项任务

  • 项目

使用 Microsoft Graph 中的待办事项 API，可将高达 25 MB 的文件附加到 todoTask。 根据文件大小，选择以下两种方法之一来附加文件：

  • 若要附加任何大小的文件，请创建上传会话，并迭代使用 PUT 上传文件的字节范围，直到上传整个文件为止。 最后一个成功 PUT 响应中的标头包括带附件 ID 的 URL。
  • 如果文件大小小于 3 MB，请对 todoTask的附件导航属性执行单个POST；了解如何为任务执行此操作。 成功的 POST 响应包括文件附件的 ID。

本文演示了第一种方法。 你将逐步了解如何创建和使用上传会话向任务添加文件附件。

第 1 步：创建上传会话

创建上传会话 以将文件附加到 todoTask。 在输入参数 attachmentInfo 中指定文件。

成功的操作返回 HTTP 201 Created 和新的 uploadSession 实例，其中包含可在后续 PUT 操作中用于上传文件各部分的非跳转 URL。 uploadSession 提供一个临时存储位置，在此位置保存文件字节数，直到完整文件上传完毕。

响应中的 uploadSession 对象还包括 nextExpectedRanges 属性，该属性指示初始上传起始位置应为字节 0。

权限

要调用此 API，需要以下权限之一。 若要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） Tasks.ReadWrite
委派（个人 Microsoft 帐户） Tasks.ReadWrite
Application 不支持。

示例：为 todoTask 创建上传会话

请求

以下示例显示创建上传会话的请求。

POST https://graph.microsoft.com/beta/me/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachments/createUploadSession
Content-Type: application/json

{
  "attachmentInfo": {
    "attachmentType": "file",
    "name": "flower",
    "size": 3483322
  }
}

响应

以下示例显示响应正文中为任务返回的 uploadSession 资源。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=",
    "expirationDateTime": "2022-06-09T10:45:27.4324526Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

步骤 2：使用上传会话上传文件的字节范围

如果要上传文件或文件的一部分，请在 uploadSession 资源的 uploadUrl 属性中，将 /content 附加到第 1 步返回的 URL，并在附加的 URL 上进行 PUT 请求。 可上传整个文件，或将文件拆分为多个字节范围。 每个字节范围需要小于 4 MB。

指定请求标头和请求正文，如以下部分所述。

请求标头

名称 类型 说明
Authorization String 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Length Int32 此操作中上传的字节数。 每个 PUT 操作的字节数上限为 4 MB。 任何大于 4 MB 的请求都将失败。 必填。
Content-Range 字符串 此操作中要上传的文件的从 0 开始的字节范围，格式为 bytes {start}-{end}/{total}。 必填。
Content-Type String MIME 类型。 指定 application/octet-stream。 必填。

请求正文

指定要附加的文件的实际字节数，它们位于由 Content-Range 请求标头指定的位置范围内。

响应

成功上传将返回 HTTP 200 OK 响应代码和 uploadSession 对象。 请注意响应对象中的以下项：

  • expirationDateTime 属性值与步骤 1 中的初始 uploadSession 返回的值相同。
  • nextExpectedRanges 指定上传开始的下一个字节位置，例如 "nextExpectedRanges":["2097152"]。 必须按顺序上传文件中的字节。
  • uploadUrl 属性不会显式返回，因为上传会话的所有 PUT 操作使用创建会话时返回的同一 URL（步骤 1）。

示例：首先上传到 todoTask

请求

以下示例显示了一个请求。

PUT https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=/content
Content-Type: application/octet-stream
Content-Length: 2097152
Content-Range: bytes 0-2097151/3483322

{
  <bytes 0-2097151 of the file to be attached, in binary format>
}

响应

下列示例响应在 nextExpectedRanges 属性中显示服务器预期的下一字节范围的起点。

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

{
  "ExpirationDateTime":"2022-06-09T10:45:27.4324526Z",
  "NextExpectedRanges":["2097152"]
}

步骤 3：继续上传字节范围，直至完整文件上传完毕

执行步骤 2 中的初始上传后，在会话的到期日期/时间前，使用步骤 2 中所述的 PUT 请求，继续上传文件中剩余的部分。 使用 nextExpectedRanges 集合确定要上传的下一个字节范围的开头。 可能会发现指定的多个范围，这些范围指明了服务器尚未收到的文件部分。 如果需要恢复中断的传输，并且客户端不能确定服务的状态，这个方法很有用。

成功上传文件的最后一个字节后，最终 PUT 操作将返回 HTTP 201 Created 响应代码和指示文件附件 URL 的 Location 标头。 可从 URL 获取附件 ID 并将其保存供以后使用。

下列示例显示在此处理步骤中将文件的最后一个字节范围上传到 todoTask 。

示例：最终上传到 todoTask

请求

以下示例显示了一个请求。

PUT https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=/content
Content-Type: application/octet-stream
Content-Length: 1386170
Content-Range: bytes 2097152-3483321/3483322

{
  <bytes 2097152-3483321 of the file to be attached, in binary format>
}

响应

下列示例显示可保存附件 ID（AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=）以供随后使用的 Location 响应标头。

HTTP/1.1 201 Created

Location: https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/Attachments/AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=
Content-Length: 0

替代步骤：取消上传会话

在上传会话到期之前的任何时间，如果必须取消上传，可使用同一初始非跳转 URL 来删除上传会话。 成功的操作返回 204 No Content 响应代码。

示例：取消上传会话

请求

以下示例显示了一个请求。

DELETE https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=

响应

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

HTTP/1.1 204 No content