attachment: createUploadSession

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

创建一个上载会话,它允许应用迭代上载文件区域,以便将该文件附加到 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 可用性

此 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 /me/messages/{id}/attachments/createUploadSession

请求标头

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

请求正文

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

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

响应

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

注意:

作为 uploadSession 响应对象的一部分返回的 uploadUrl 属性是一个不透明的 URL,供后续PUT查询上传文件的字节范围。 它包含后续查询(在 expirationDateTime 到期)的PUT相应身份验证令牌。 不要自定义此 URL。

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

示例

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

下面的示例显示了如何创建一个上传会话,您可以在对指定消息的后续文件上传操作中使用该会话。

请求

POST https://graph.microsoft.com/beta/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/beta/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/beta/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/beta/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-"
    ]
}