通过

附件：createUploadSession

  • 项目

命名空间：microsoft.graph

创建允许应用以迭代方式上传文件范围的上传会话，以便将文件附加到指定的 Outlook 项目。 该项可以是 消息 或 事件。

如果文件大小介于 3 MB 和 150 MB 之间，请使用此方法附加文件。 若要附加小于 3 MB 的文件，请对 Outlook 项目的附件导航属性执行操作POST;请参阅如何针对邮件或事件执行此操作。

作为响应的一部分，此操作返回可在后续顺序 PUT 查询中使用的上传 URL。 通过每个 PUT 操作的请求标头，可以指定要上传的字节的确切范围。 这允许恢复传输，以防在上传过程中断开网络连接。

下面是使用上传会话将文件附加到 Outlook 项目的步骤：

  1. 创建上传会话。
  2. 在该上传会话中，每次) 时，迭代上传字节范围 (最大为 4 MB，直到上传文件的所有字节，并且文件已附加到指定项。
  3. 保存附件的 ID 以供将来访问。
  4. 可选：删除上传会话。

有关示例，请参阅 将大型文件附加到 Outlook 邮件或事件 。

提示

Exchange Online允许管理员自定义 Microsoft 365 邮箱的邮件大小限制，包括任何邮件附件。 默认情况下，此消息大小限制为 35 MB。 了解如何 自定义最大邮件大小 以支持大于租户默认限制的附件。

重要

如果要将大文件附加到共享或委派邮箱中的邮件或事件，请注意 已知问题 。

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

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

权限

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

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Calendars.ReadWrite Mail.ReadWrite
委派（个人 Microsoft 帐户） Calendars.ReadWrite Mail.ReadWrite
应用程序 Calendars.ReadWrite Mail.ReadWrite

HTTP 请求

若要创建上传会话以将文件附加到 事件，请执行以下操作：

POST /me/events/{id}/attachments/createUploadSession
POST /users/{id | userPrincipalName}/events/{id}/attachments/createUploadSession

若要创建用于将文件附加到 邮件的上传会话，请执行以下操作：

POST /me/messages/{id}/attachments/createUploadSession
POST /users/{id | userPrincipalName}/messages/{id}/attachments/createUploadSession

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

在请求正文中，提供具有以下参数的 JSON 对象。

参数 类型 说明
AttachmentItem attachmentItem 表示要上传和附加的项的属性。 至少指定附件类型 (file) 、名称和文件大小。

响应

如果成功，此方法在响应正文中返回响应 201 Created 代码和新的 uploadSession 对象。

注意：

作为 uploadSession 响应对象的一部分返回的 uploadUrl 属性是后续 PUT 查询上传文件的字节范围的不透明 URL。 它包含相应的身份验证令牌，用于在 expirationDateTime 之前过期的后续PUT查询。 请勿自定义此 URL。

nextExpectedRanges 属性指定要从中上传的下一个文件字节位置，"NextExpectedRanges":["2097152"]例如 。 必须按顺序上传文件中的字节。

示例

示例 1：创建上传会话以将大型附件添加到草稿邮件

以下示例演示如何创建一个上传会话，该会话可用于对指定消息的后续文件上传操作。

请求

POST https://graph.microsoft.com/v1.0/me/messages/AAMkADI5MAAIT3drCAAA=/attachments/createUploadSession
Content-type: application/json

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

响应

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/v1.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0uAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI",
    "expirationDateTime": "2019-09-25T01:09:30.7671707Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

示例 2：创建上传会话以将大型内联附件添加到草稿邮件

以下示例演示如何创建可用于向草稿邮件添加大型内联附件的上传会话。

对于内联附件，将 isInline 属性 true 设置为 ，并使用 contentId 属性为附件指定 CID，如下所示。 在草稿邮件的正文中，使用相同的 CID 值来指示希望使用 CID HTML 引用标记包含附件的位置，例如 <img src="cid:my_inline_picture">。 成功上传文件后，呈现的邮件将附件包含在指定位置的邮件正文中。

请求

POST https://graph.microsoft.com/v1.0/me/messages/AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=/attachments/createUploadSession
Content-type: application/json

{
  "AttachmentItem": {
    "attachmentType": "file",
    "name": "scenary",
    "size": 7208534,
    "isInline": true,
    "contentId": "my_inline_picture"
  }
}

响应

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/gv1.0/users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=')/AttachmentSessions('AAMkAGUwNjQ4ZjIxLTAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IjFTeXQ1bXdXYVh5UFJ",
    "expirationDateTime": "2021-12-27T14:20:12.9708933Z",
    "nextExpectedRanges": [
        "0-"
    ]
}