获取附件
命名空间：microsoft.graph
重要
Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。
警告
应更新将此功能与 Outlook 任务配合使用的现有应用，因为 Outlook 任务正在弃用。 有关详细信息 ，请参阅公共预览版中的 To Do API 。
读取附加到用户 事件、 邮件、 Outlook 任务或组 帖子的附件的属性、关系或原始内容。
附件可以是下列类型之一：
- 文件。 采用编程方式，这是 fileAttachment 资源。 请参阅示例 1。
- Outlook 项目（联系人、事件或邮件）。 采用编程方式，项目附件是 itemAttachment 资源。 可以使用
$expand来进一步获取该项目属性，包括多达 30 级的任何嵌套附件。 请参阅 示例 3 和 示例 4。 - 指向存储在云中的文件的链接。 采用编程方式，这是 referenceAttachment 资源。 请参阅 示例 5。
所有这些类型的附件都派生自 attachment 资源。
此 API 可用于以下国家级云部署。
| 全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
获取文件或项目附件的原始内容
你可以附加路径段 /$value 以获取文件或项目附件的原始内容。
对于文件附件，内容类型基于其原始内容类型。 请参阅 示例 6。
对于作为联系人、事件或邮件的项目附件，返回的原始内容为 MIME 格式。
| 项目附件类型 | 返回的原始内容 |
|---|---|
| 联系人 | vCard MIME 格式。 请参阅 示例 7。 |
| 事件 | iCal MIME 格式。 请参阅 示例 8。 |
| 邮件 | MIME 格式。 请参阅 示例 9。 |
尝试获取参考附件的 $value 时返回 HTTP 405。
注意
当请求某些文件时，MIME 可以对响应中的字节流输出进行编码，并提供链接以电子邮件附件的形式下载文件。
权限
根据附件附加到的资源 (事件、 消息、 outlookTask 或 post) ，以及请求的权限类型 (委托或应用程序) ，下表中指定的权限是调用此 API 所需的最低特权。 若要了解其他信息， 在 特权权限之前要特别小心，在"权限" 中搜索。
| 支持的资源 | 委派（工作或学校帐户） | 委派（个人 Microsoft 帐户） | 应用程序 |
|---|---|---|---|
| 事件 | Calendars.Read | Calendars.Read | Calendars.Read |
| 邮件 | Mail.Read | Mail.Read | Mail.Read |
| outlookTask | Tasks.Read | Tasks.Read | 不支持 |
| 帖子 | Group.Read.All | 不支持 | 不支持 |
HTTP 请求
本部分显示每个实体的 HTTP GET 请求语法，这些实体 (事件、 邮件、 Outlook 任务和支持附件的 发布) ：
- 若要获取附件的属性和关系，请指定附件 ID 以索引到 附件 集合中，附加到指定的 事件、 邮件、 Outlook 任务或 post 实例。
- 如果附件是文件或 Outlook 项目（联系人、事件或邮件），则可以通过将路径段
/$value附加到请求 URL 来进一步获取附件的原始内容。
事件的附件：
GET /me/events/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/events/{id}/attachments/{id}
GET /me/events/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/events/{id}/attachments/{id}/$value
用户邮箱中 邮件 的附件：
GET /me/messages/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/messages/{id}/attachments/{id}
GET /me/messages/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/messages/{id}/attachments/{id}/$value
包含在用户邮箱中顶级 mailFolder 中的邮件的附件：
GET /me/mailFolders/{id}/messages/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}/attachments/{id}
GET /me/mailFolders/{id}/messages/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}/attachments/{id}/$value
包含在用户邮箱中 mailFolder 的子文件夹中的邮件附件：
GET /me/mailFolders/{id}/childFolders/{id}/.../messages/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/childFolders/{id}/messages/{id}/attachments/{id}
GET /me/mailFolders/{id}/childFolders/{id}/.../messages/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/mailFolders/{id}/childFolders/{id}/messages/{id}/attachments/{id}/$value
前面的示例演示了一个嵌套级别，但消息可以位于子级等子级中。
Outlook 任务的附件：
GET /me/outlook/tasks/{id}/attachments/{id}
GET /users/{id}/outlook/tasks/{id}/attachments/{id}
GET /me/outlook/tasks/{id}/attachments/{id}/$value
GET /users/{id}/outlook/tasks/{id}/attachments/{id}/$value
GET /groups/{id}/threads/{id}/posts/{id}/attachments/{id}
GET /groups/{id}/conversations/{id}/threads/{id}/posts/{id}/attachments/{id}
GET /groups/{id}/threads/{id}/posts/{id}/attachments/{id}/$value
GET /groups/{id}/conversations/{id}/threads/{id}/posts/{id}/attachments/{id}/$value
可选的查询参数
此方法支持一些 OData 查询参数 来帮助自定义响应。
使用 $expand 以获取项目附件的属性（联系人、事件或邮件）。 请参阅 示例 3 和 示例 4。
请求标头
| 名称 | 类型 | 说明 |
|---|---|---|
| Authorization | string | 持有者 {token}。 必填。 |
请求正文
请勿提供此方法的请求正文。
响应
如果成功，GET 方法将 200 OK 返回响应代码。
如果要获取附件的属性和关系，则响应正文应包含 attachment 对象。 返回附件类型的属性：fileAttachment、itemAttachment 或 referenceAttachment。
如果要获取文件或项目附件的原始内容，则响应正文应包含附件的原始值。
示例
示例 1：获取文件附件的属性
请求
以下示例演示了获取邮件上文件附件属性的请求。
GET https://graph.microsoft.com/beta/me/messages/AAMkAGUzY5QKjAAA=/attachments/AAMkAGUzY5QKjAAABEgAQAMkpJI_X-LBFgvrv1PlZYd8=
响应
以下示例显示了相应的响应。 注意：为了提高可读性，可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages('AAMkAGUzY5QKjAAA%3D')/attachments/$entity",
"@odata.type": "#microsoft.graph.fileAttachment",
"id": "AAMkAGUzY5QKjAAABEgAQAMkpJI_X-LBFgvrv1PlZYd8=",
"lastModifiedDateTime": "2019-04-02T03:41:29Z",
"name": "Draft sales invoice template.docx",
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"size": 13068,
"isInline": false,
"contentId": null,
"contentLocation": null,
"contentBytes": "UEsDBBQABgAIAAAAIQ4AAAAA"
}
示例 2：获取项目附件的属性
请求
下一个示例演示如何在邮件上获取项目附件。 返回 itemAttachment 的属性。
GET https://graph.microsoft.com/beta/me/messages/AAMkADA1M-zAAA=/attachments/AAMkADA1M-CJKtzmnlcqVgqI=
响应
以下示例显示了相应的响应。 注意：为了提高可读性，可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/messages('AAMkADA1M-zAAA%3D')/attachments/$entity",
"@odata.type":"#microsoft.graph.itemAttachment",
"id":"AAMkADA1M-CJKtzmnlcqVgqI=",
"lastModifiedDateTime":"2017-07-21T00:20:34Z",
"name":"Reminder - please bring laptop",
"contentType":null,
"size":32005,
"isInline":false
}
示例 3：展开并获取附加到邮件的项目的属性
请求
下一个示例演示如何使用 $expand 来获取附加到该邮件的项目（联系人、事件或邮件）的属性。 在此示例中，该项目是一封邮件；还会返回该附加邮件的属性。
GET https://graph.microsoft.com/beta/me/messages/AAMkADA1M-zAAA=/attachments/AAMkADA1M-CJKtzmnlcqVgqI=/?$expand=microsoft.graph.itemattachment/item
响应
以下示例显示了相应的响应。 注意：为了提高可读性，可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/messages('AAMkADA1M-zAAA%3D')/attachments/$entity",
"@odata.type":"#microsoft.graph.itemAttachment",
"id":"AAMkADA1MCJKtzmnlcqVgqI=",
"lastModifiedDateTime":"2017-07-21T00:20:34Z",
"name":"Reminder - please bring laptop",
"contentType":null,
"size":32005,
"isInline":false,
"item":{
"@odata.type":"#microsoft.graph.message",
"id":"",
"createdDateTime":"2017-07-21T00:20:41Z",
"lastModifiedDateTime":"2017-07-21T00:20:34Z",
"receivedDateTime":"2017-07-21T00:19:55Z",
"sentDateTime":"2017-07-21T00:19:52Z",
"hasAttachments":false,
"internetMessageId":"<BY2PR15MB05189A084C01F466709E414F9CA40@BY2PR15MB0518.namprd15.prod.outlook.com>",
"subject":"Reminder - please bring laptop",
"bodyPreview": "PFA\r\n\r\nThanks,\r\nRob",
"importance":"normal",
"conversationId":"AAQkADA1MzMyOGI4LTlkZDctNDkzYy05M2RiLTdiN2E1NDE3MTRkOQAQAMG_NSCMBqdKrLa2EmR-lO0=",
"conversationIndex":"AQHTAbcSwb41IIwGp0qstrYSZH+U7Q==",
"isDeliveryReceiptRequested":false,
"isReadReceiptRequested":false,
"isRead":false,
"isDraft":false,
"webLink":"https://outlook.office365.com/owa/?ItemID=AAMkADA1M3MTRkOQAAAA%3D%3D&exvsurl=1&viewmodel=ReadMessageItem",
"internetMessageHeaders": [ ],
"body":{
"contentType":"html",
"content":"<html><head>\r\n</head>\r\n<body>\r\n</body>\r\n</html>"
},
"sender":{
"emailAddress":{
"name":"Adele Vance",
"address":"AdeleV@contoso.com"
}
},
"from":{
"emailAddress":{
"name":"Adele Vance",
"address":"AdeleV@contoso.com"
}
},
"toRecipients":[
{
"emailAddress":{
"name":"Alex Wilbur",
"address":"AlexW@contoso.com"
}
}
],
"ccRecipients":[
{
"emailAddress":{
"name":"Adele Vance",
"address":"AdeleV@contoso.com"
}
}
],
"flag":{
"flagStatus":"notFlagged"
}
}
}
示例 4：展开并获取附加到邮件的项目的属性，包括该项目的任何附件
请求
下一个示例使用与示例 3 相同的请求 以通过使用 $expand 获取邮件上项目附件的属性。 在这种情况下，由于附加项目也具有文件附件，因此答复中也包含文件附件的属性。
GET https://graph.microsoft.com/beta/me/messages/AAMkADA1M-zAAA=/attachments/AAMkADA1M-CJKtzmnlcqVgqI=/?$expand=microsoft.graph.itemattachment/item
响应
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/messages('AAMkADA1M-zAAA%3D')/attachments(microsoft.graph.itemAttachment/item())/$entity",
"@odata.type": "#microsoft.graph.itemAttachment",
"id": "AAMkADA1MCJKtzmnlcqVgqI=",
"lastModifiedDateTime": "2021-01-06T13:28:11Z",
"name": "Nested Message With Attachment",
"contentType": null,
"size": 465916,
"isInline": false,
"item": {
"@odata.type": "#microsoft.graph.message",
"id": "",
"createdDateTime": "2021-01-06T13:28:30Z",
"lastModifiedDateTime": "2021-01-06T13:27:40Z",
"receivedDateTime": "2021-01-06T13:27:25Z",
"sentDateTime": "2021-01-06T13:27:04Z",
"hasAttachments": true,
"internetMessageId": "<BY2PR15MB05189A084C01F466709E414F9CA40@BY2PR15MB0518.namprd15.prod.outlook.com>",
"subject": "Nested Message With Attachment",
"bodyPreview": "PFAThanks,Adele",
"importance": "normal",
"conversationId": "AAQkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWQyZjg2YWQwMTNkZAAQAO6hkp84oMdGm6ZBsSH72sE=",
"conversationIndex": "AQHW5C+U7qGSnzigx0abpkGxIfvawQ==",
"isDeliveryReceiptRequested": false,
"isReadReceiptRequested": false,
"isRead": true,
"isDraft": false,
"webLink": "https://outlook.office365.com/owa/?ItemID=AAMkADA1M3MTRkOQAAAA%3D%3D&exvsurl=1&viewmodel=ItemAttachment",
"internetMessageHeaders": [],
"body": {
"contentType": "html",
"content": "<html><head>\r\n</head>\r\n<body>\r\n</body>\r\n</html>"
},
"sender": {
"emailAddress": {
"name": "Adele Vance",
"address": "Adele.Vance@microsoft.com"
}
},
"from": {
"emailAddress": {
"name": "Adele Vance",
"address": "Adele.Vance@microsoft.com"
}
},
"toRecipients": [
{
"emailAddress": {
"name": "Adele Vance",
"address": "Adele.Vance@microsoft.com"
}
}
],
"flag": {
"flagStatus": "notFlagged"
},
"attachments": [
{
"@odata.type": "#microsoft.graph.fileAttachment",
"@odata.mediaContentType": "application/pdf",
"id": "AAMkADg3NTYULmbsDYNg==",
"lastModifiedDateTime": "2021-01-21T14:56:18Z",
"name": "Info.pdf",
"contentType": "application/pdf",
"size": 417351,
"isInline": false,
"contentId": null,
"contentLocation": null,
"contentBytes": "JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlbi1JTikgL1N0cnVjdFRyZWVSb29"
}
]
}
}
示例 5：获取参考附件的属性
请求
以下示例显示了获取事件引用附件的请求。
GET https://graph.microsoft.com/beta/me/events/AAMkAGE1M88AADUv0uAAAG=/attachments/AAMkAGE1Mg72tgf7hJp0PICVGCc0g=
响应
以下示例显示了相应的响应。 注意：为了提高可读性，可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users/ddfcd489-628b-40d7-b48b-57002df800e5/events/AAMkAGE1M88AADUv0uAAAG%3D/attachments/$entity",
"@odata.type": "#microsoft.graph.referenceAttachment",
"id": "AAMkAGE1Mg72tgf7hJp0PCGVCIc0g=",
"lastModifiedDateTime": "2016-03-12T06:04:38Z",
"name": "Personal pictures",
"contentType": null,
"size": 382,
"isInline": false,
"sourceUrl": "https://contoso.com/personal/mario_contoso_net/Documents/Pics",
"providerType": "oneDriveConsumer",
"thumbnailUrl": null,
"previewUrl": null,
"permission": "edit",
"isFolder": true
}
示例 6：获取邮件上文件附件的原始内容
请求
以下示例演示了获取已附加到消息的 Word 文件的原始内容的请求。
GET https://graph.microsoft.com/beta/me/messages/AAMkAGUzY5QKjAAA=/attachments/AAMkAGUzY5QKjAAABEgAQAMkpJI_X-LBFgvrv1PlZYd8=/$value
响应
以下示例显示了相应的响应。 实际响应正文包含文件附件的原始字节，为简洁起见，此处为缩写。
HTTP/1.1 200 OK
{Raw bytes of the file}
示例 7：获取邮件上联系人附件的 MIME 原始内容
请求
以下示例演示请求获取已附加到邮件的联系人项目的原始内容。
GET https://graph.microsoft.com/beta/me/messages/AAMkADI5MAAGjk2PxAAA=/attachments/AAMkADI5MAAGjk2PxAAABEgAQACEJqrbJZBNIlr3pGFvd9K8=/$value
响应
以下示例显示了相应的响应。
HTTP/1.1 200 OK
BEGIN:VCARD
PROFILE:VCARD
VERSION:3.0
MAILER:Microsoft Exchange
PRODID:Microsoft Exchange
FN:Alex Wilbur
N:Wilbur;Alex;;;
NOTE:Sunday\, June 10\, 2012 5:44 PM:\nGutter\, window cleaning\, pressure
washing\, roof debris blowing\n
ORG:Contoso;
CLASS:PUBLIC
ADR;TYPE=WORK,PREF:;;4567 Main St;Buffalo;NY;98052;United States of America
LABEL;TYPE=WORK,PREF:4567 Main St\nBuffalo\, NY 98052
ADR;TYPE=HOME:;;;;;;
ADR;TYPE=POSTAL:;;;;;;
TEL;TYPE=WORK:(425) 555-0100
TITLE:
X-MS-IMADDRESS:
REV;VALUE=DATE-TIME:2019-04-09T02:13:31,161Z
END:VCARD
示例 8：获取邮件上事件附件的 MIME 原始内容
请求
以下示例演示了获取已附加到消息的事件的原始内容的请求。
GET https://graph.microsoft.com/beta/me/messages/AAMkADVIOAAA=/attachments/AAMkADVIOAAABEgAQACvkutl6c4FMifPyS6NvXsM=/$value
响应
以下示例显示了相应的响应。
HTTP/1.1 200 OK
BEGIN:VCALENDAR
METHOD:PUBLISH
PRODID:Microsoft Exchange Server 2010
VERSION:2.0
BEGIN:VTIMEZONE
TZID:Pacific Standard Time
BEGIN:STANDARD
DTSTART:16010101T020000
TZOFFSETFROM:-0700
TZOFFSETTO:-0800
RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=1SU;BYMONTH=11
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:16010101T020000
TZOFFSETFROM:-0800
TZOFFSETTO:-0700
RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=2SU;BYMONTH=3
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
ORGANIZER;CN=Adele Vance:MAILTO:adelev@contoso.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=Adele Vance:MAILTO:adelev@contoso.com
DESCRIPTION;LANGUAGE=en-US:\n
UID:040000008200
SUMMARY;LANGUAGE=en-US:Review Megan's docs
DTSTART;TZID=Pacific Standard Time:20190409T140000
DTEND;TZID=Pacific Standard Time:20190409T160000
CLASS:PUBLIC
PRIORITY:5
DTSTAMP:20190409T211833Z
TRANSP:OPAQUE
STATUS:CONFIRMED
SEQUENCE:0
LOCATION;LANGUAGE=en-US:
X-MICROSOFT-CDO-APPT-SEQUENCE:0
X-MICROSOFT-CDO-OWNERAPPTID:0
X-MICROSOFT-CDO-BUSYSTATUS:BUSY
X-MICROSOFT-CDO-INTENDEDSTATUS:BUSY
X-MICROSOFT-CDO-ALLDAYEVENT:FALSE
X-MICROSOFT-CDO-IMPORTANCE:1
X-MICROSOFT-CDO-INSTTYPE:0
X-MICROSOFT-DONOTFORWARDMEETING:FALSE
X-MICROSOFT-DISALLOW-COUNTER:FALSE
X-MICROSOFT-LOCATIONS:[]
BEGIN:VALARM
DESCRIPTION:REMINDER
TRIGGER;RELATED=START:-PT15M
ACTION:DISPLAY
END:VALARM
END:VEVENT
END:VCALENDAR
示例 9：获取邮件上的会议邀请项目附件的 MIME 原始内容
请求
以下示例演示请求获取已附加到邮件的 eventMessage 类型) (会议邀请的原始内容。 eventMessage 实体基于邮件类型。
GET https://graph.microsoft.com/beta/me/messages/AAMkAGUzY5QKiAAA=/attachments/AAMkAGUzY5QKiAAABEgAQAK8ktgiIO19OqkvUZAqLmyQ=/$value
响应
以下示例显示了相应的响应。
响应正文包含 MIME 格式的 eventMessage 附件。 为简洁起见， eventMessage 的正文将被截断。 可通过实际调用返回完整的邮件正文。
HTTP/1.1 200 OK
From: Megan Bowen <MeganB@contoso.com>
To: Adele Vance <AdeleV@contoso.com>
Subject: Let's go for lunch
Thread-Topic: Let's go for lunch
Thread-Index: AdTPqxOmg4AXoJV960a1j5NrJCHYjA==
X-MS-Exchange-MessageSentRepresentingType: 1
Date: Thu, 28 Feb 2019 21:17:58 +0000
Message-ID:
<CY4PR2201MB1046E9C83FC42478EF4EE283C9750@CY4PR2201MB1046.namprd22.prod.outlook.com>
Content-Language: en-US
X-MS-Has-Attach:
X-MS-Exchange-Organization-SCL: -1
X-MS-TNEF-Correlator:
X-MS-Exchange-Organization-RecordReviewCfmType: 0
Content-Type: multipart/alternative;
boundary="_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_"
MIME-Version: 1.0
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_
Content-Type: text/plain; charset="us-ascii"
Does mid month work for you?
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_
Content-Type: text/html; charset="us-ascii"
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body>
Does mid month work for you?
</body>
</html>
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_
Content-Type: text/calendar; charset="utf-8"; method=REQUEST
Content-Transfer-Encoding: base64
QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVRVUVTVA0KUFJPRElEOk1pY3Jvc29mdCBFeGNoYW5n
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_--
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈