在 Microsoft Graph PowerShell SDK 中使用邮件文件夹和消息

处理文件夹和消息

Exchange Online 邮箱实际上塞满了信息。不仅仅是电子邮件会进入文件夹。邮箱还保存日历事件、联系人、任务、合规记录以及用户和开发人员存储的任何其他内容。

Exchange Web 服务 (EWS) 长期以来一直是用于访问邮箱数据的 API。但微软将从 2026 年 10 月 1 日起阻止非微软应用程序的 EWS 访问。即使微软在覆盖范围上还有一些差距需要弥补，Graph API 仍然是应用程序开发人员前进的道路。微软在为 Exchange Online 管理提供图形 API 方面仍然没有取得太大进展，但确实存在用于访问最重要的邮箱元素的 API：文件夹、消息、日历事件和联系人。任务由长期计划处理，以统一 Microsoft 365 内的任务。

如果管理员想要访问邮箱内容，他们应该使用图形 API。您可以使用交互式 Microsoft Graph PowerShell SDK 会话针对您自己的邮箱测试此处说明的命令。访问其他用户邮箱需要应用程序同意 Mail.Read 应用程序权限。访问邮箱内容的应用程序显然可以访问机密或敏感信息，因此请考虑使用应用程序的 RBAC 来限制应用程序对邮箱的访问。

访问邮箱中的邮件文件夹

邮箱文件夹被定义为图形资源。用于在邮箱中查找用户可访问的邮件文件夹的 cmdlet 是 Get-MgUserMailFolder。邮件文件夹是一个重要的点。 Get-MgUserMailFolder 返回的文件夹集不包括日历和联系人等文件夹，因为这些文件夹是为了特定目的而创建的。 Get-MgUserMailFolder 返回的集合包括 IPM 子树中可以保存邮件消息的任何文件夹（即电子邮件客户端可见的文件夹），包括由邮箱所有者创建的文件夹。

下面显示的示例使用 All 参数指示图形返回完整的邮件文件夹集，而不是前 10 个，这是 cmdlet 的默认页面大小。 IncludeHiddenFolders 参数设置为 true 以使图表在返回的集合中包含隐藏的邮件文件夹。

[array]$Folders = Get-MgUserMailFolder -Userid $UserId -All -IncludeHiddenFolders $true

为单个邮件文件夹返回的属性如下所示。 id 是最重要的属性，因为需要它来获取文件夹中存储的消息的详细信息。

ChildFolderCount              : 0
ChildFolders                  :
DisplayName                   : Inbox
Id                            : AAMkADAzNzBmMzU0LTI3NTItNDQzNy04NzhkLWNmMGU1MzEwYThkNAAuAAAAAAB_7ILpFNx8TrktaK8VYWerAQBe9CuwLc2fTK7W46L1SAp9AAAA2lHHAAA=
IsHidden                      : False
MessageRules                  :
Messages                      :
MultiValueExtendedProperties  :
ParentFolderId                : AAMkADAzNzBmMzU0LTI3NTItNDQzNy04NzhkLWNmMGU1MzEwYThkNAAuAAAAAAB_7ILpFNx8TrktaK8VYWerAQBe9CuwLc2fTK7W46L1SAp9AAAA2lHEAAA=
SingleValueExtendedProperties :
TotalItemCount                : 5517
UnreadItemCount               : 0
AdditionalProperties          : {[sizeInBytes, 1938417762]}

文件夹可以有子文件夹。例如，如果您删除文件夹，Exchange 会将该文件夹移动到“已删除邮件”文件夹，并在该文件夹中成为子文件夹。此示例使用 Get-MgUserMailFolderChildFolder cmdlet 检索“已删除邮件”文件夹中找到的子文件夹的详细信息。已删除的文件夹包含 2 项，总大小为 393,465 字节。

[array]$ChildFolders = Get-MgUserMailFolderChildFolder -Userid $UserId -MailFolderId 'DeletedItems'

$ChildFolders | Format-Table DisplayName, TotalItemCount, AdditionalProperties

DisplayName   TotalItemCount AdditionalProperties
-----------   -------------- --------------------
Project Helia              2 {[sizeInBytes, 393465]}

在这种情况下，该命令使用“众所周知的文件夹名称”来标识要处理的文件夹。众所周知的文件夹是 Outlook 默认创建的文件夹。 Microsoft 在线记录了著名的文件夹。如果文件夹不是众所周知的文件夹，则必须传递文件夹标识符。例如，此命令使用选定文件夹的标识符：

$Folder = $Folders[5]
$ChildFolders = Get-MgUserMailFolderChildFolder -Userid $UserId -MailFolderId $Folder.id

访问消息

检索邮件文件夹集后，下一步是使用 Get-MgUserMailFolderMessage cmdlet 从文件夹中获取邮件。需要记住的一些要点是：

• 消息的默认页面大小为 10。要通过减少获取项目的往返次数来加快检索速度，请使用较大的页面大小（最大页面大小为 999）。
• 仅检索邮件消息。邮件文件夹可以容纳不同类型的项目的混合。但是，Get-MgUserMailFolderMessage 只能查找邮件类别为 IPM.Note 的项目。
• 出于性能考虑，限制请求返回的属性数量至关重要。图形请求总是如此，但在处理消息时限制属性非常重要。

假设选择了一个文件夹，我们可以运行Get-MgUserMailFolderMessage来获取邮件项。下面是一个示例，其中 cmdlet 参数将提取限制为三个属性，并使用最大页面大小来最大限度地缩短检索时间：

[array]$Items = Get-MgUserMailFolderMessage -UserId $UserId -MailFolderId $Folder.id -All `
   -Property sender, createdDateTime, subject -PageSize 999

为了说明在处理大量对象时使用大页面大小的重要性，对包含 26,465 个项目的文件夹运行上述命令花费了 11.283 秒，页面大小为 999。使用默认页面大小 (10) 花费了 188 秒。这是一个很大的区别。

使用单值扩展属性

单值扩展属性包含消息、日历事件和联系人等对象的单个值。这些是可选属性，其中许多属性源自 MAPI 属性，并且不包含在消息资源类型中。多值扩展属性也是可用的，但我不会在这里讨论它们。

Microsoft 使用 MAPI（消息传递应用程序编程接口）构建了 Exchange Server。自 1992 年以来，MAPI 发生了许多变化和更新，以支持服务器和客户端 (Outlook) 的开发。如今，Exchange Server 协议主属性列表中列出了 1080 个标记，其中包括邮件的垃圾邮件可信度、HTML 正文部分、传递时间、对话索引等标记。您可以通过使用 MFCMAPI 实用程序检查消息来查看这些属性。

单值扩展属性存储一些您希望位于默认集中的消息属性。这些属性中有PidTagMessageSize，它存储消息的大小（以字节为单位）。如上所述，为邮箱文件夹返回的属性包括文件夹中项目的总大小，但邮件不包含大小属性，除非您获取PidTagMessageSize。以下是如何修改上面使用的 Get-MgUserMailFolderMessage 命令以包含邮件大小的检索：

[array]$Items = Get-MgUserMailFolderMessage -UserId $UserId -MailFolderId $Folder.id -All `
   -Property sender, createdDateTime, subject -PageSize 999 `
   -ExpandProperty "singleValueExtendedProperties(`$filter=Id eq 'LONG 0x0E08')"

为了获取消息大小，cmdlet 使用 ExpandProperty 参数指示 Graph 扩展由过滤子句标识的单值扩展属性的值，该子句使用唯一标记标识符 (0x0E08) 来定位该财产。标签标识符在单值扩展属性的协议定义中进行了描述（请参阅上面的 PidTagMessageSize 链接）。

单个项目扩展属性以数组形式返回。要使用消息大小（以字节为单位），请从数组中提取值：

$Item.SingleValueExtendedProperties

Id         Value
--         -----
Long 0xe08 169616

$Item.SingleValueExtendedProperties.value
169616

本文讨论的脚本中提供了使用PidTagMessageSize报告消息大小的示例。该脚本使用 Graph API 请求来获取属性。

处理其他邮箱内容

本文概述的步骤是使用 Microsoft Graph PowerShell SDK cmdlet 处理邮件文件夹和消息的基础知识。处理日历和联系人需要一组不同的 cmdlet 和权限。

例如，要查找邮箱可用的日历集，需要先获得 Calendars.Read 权限，然后再运行 Get-MgUserCalendar cmdlet。该组日历包括用户可以访问的任何日历。此代码获取该设置并提取默认日历：

[array]$Calendars = Get-MgUserCalendar -UserId $UserId
$DefaultUserCalendar = $Calendars | Where-Object {$_.Name -eq 'Calendar'}

使用Get-MgUserCalendarView cmdlet 从日历中获取事件。此示例搜索日历以查找与日期范围的过滤器匹配的事件：

[array]$Events = Get-MgUserCalendarView -UserId $UserId -CalendarId $DefaultUserCalendar.Id -EndDateTime '2024-06-30' -StartDateTime '2024-06-01' -Filter "Subject eq 'Important Meeting '"

检索联系人时也会发生同样的情况。 Contact.Read 权限允许使用 Get-MgContact cmdlet 来获取存储在邮箱的“联系人”文件夹中的个人联系人的详细信息。

[array]$Contacts = Get-MgContact -All

一旦您习惯了图表的工作方式，一切都会遵循逻辑路径。我想这就是拥有一组明确定义的资源和 API 方法的意义所在。至少，我认为是的。考虑到这一点，我希望此处给出的建议可以帮助您浏览邮箱文件夹和邮件。