使用 PowerShell 的报告室邮箱每周时间表

使用 PowerShell 提取、格式化每周房间时间表并将其通过电子邮件发送给指定收件人

一位读者询问是否可以将房间邮箱中安排的活动详细信息通过电子邮件发送到通讯组列表。很容易设想此功能有用的场景。例如，一个团队可能负责管理某个位置的一组会议室，并希望了解一周甚至一天前的活动。无论如何，Exchange Online 中不存在这样的功能，所以让我们看看 PowerShell 可以实现什么功能。

脚本中的初始步骤可能是：

• 计算报告期。此示例报告从星期一开始的下周的事件。
• 查找所有房间邮箱（可能仅限于某个位置）。
• 对于每个房间，检查报告期间是否存在任何事件。如果找到，请提取其详细信息。

找到数据后，接下来就需要以不同的方式提供信息。例如，您可能需要打印一周的活动报告，或者按照最初的要求，脚本应发送电子邮件以向人们通报特定房间的活动最新情况。

该脚本使用注册的 Entra ID 应用程序来验证和保护访问令牌，以允许其查询图形数据。应用程序必须同意使用以下图形权限：

• Calendar.Read：从日历文件夹中读取事件。
• Place.Read.All：读取地点的详细信息，例如房间邮箱。
• User.Read.All：读取用户帐户的详细信息。
• MailSend.All：通过电子邮件发送每周时间表。

Mail.Send.All 权限允许从租户中的任何邮箱发送电子邮件。要限制访问，请考虑使用应用程序的 RBAC 来限制对用于分发每周计划更新的邮箱的访问。

您可以从 GitHub 下载该脚本。

确定报告日期

去年，我写了一篇关于从房间邮箱日历中保存的事件数据中提取房间邮箱统计信息的文章。该脚本使用 Graph API 请求来查找房间邮箱并查询事件。从概念上讲，上面概述的初始步骤类似于提取房间统计信息所执行的步骤。不同之处在于，分析房间使用情况是对数据的回顾，而此脚本的目的是了解房间将来将举办哪些活动。

我决定报告期为下周一至下周一。此代码获取当前日期并确定今天是否是星期一。如果是，则报告期的开始日期为今天。如果没有，开始日期是下周一。计算出日期后，代码会创建两个可排序格式的变量，以便在查询房间邮箱中的日历事件时使用。

[datetime]$Today = (Get-Date).date
# If today is Monday, we report on the current week. Otherwise, we report on the next week
If ($Today.DayOfWeek.value__ -eq 1) {
    [datetime]$NextMonday = Get-Date($Today) -format 'dd-MMM-yyyy'
} Else {
    [datetime]$NextMonday = Get-Date($Today.AddDays(2 + $Today.DayOfWeek.value__)) -format 'dd-MMM-yyyy'
}
# Calculate the following Monday after the start date
[datetime]$NextMondayAfter = Get-Date($NextMonday).AddDays(7) -format 'dd-MMM-yyyy'

# Create sortable dates that can be used with the Graph request to find calendar data
$StartDate = Get-Date($NextMonday) -format s
$EndDate = Get-Date($NextMondayAfter) -format s

寻找房间邮箱

存在多种技术来查找房间邮箱集。您可以使用 Exchange Online 管理模块中的 Get-ExoMailbox cmdlet 来运行如下命令：

[array]$RoomMailboxes = Get-ExoMailbox -RecipientTypeDetails RoomMailbox -ResultSize Unlimited

无需加载 Exchange Online 管理模块即可查找房间邮箱集。相反，该脚本使用 Graph Places API 来检索房间邮箱，代码如下：

$Uri = "https://graph.microsoft.com/V1.0/places/microsoft.graph.room"
[Array]$RoomMailboxes = Get-GraphData -Uri $Uri -AccessToken $Token

对 Get-GraphData 的引用不适用于 cmdlet。相反，它是一个使执行图形请求更容易的函数，因为该函数负责错误处理和分页。结果是一个包含房间邮箱集的数组。如果您只想报告某些房间的日历事件，请应用过滤器来选择目标邮箱。

处理日历

为了从会议室邮箱日历中检索事件，该脚本使用邮箱的电子邮件地址以及要查询的时间段的开始和结束日期等参数构建 URI。

$Uri = ("https://graph.microsoft.com/V1.0/users/{0}/calendar/calendarView?startDateTime={1}&endDateTime={2}" -f $Room.emailAddress, $StartDate, $EndDate)
[array]$CalendarData = Get-GraphData -Uri $Uri -AccessToken $Token

生成的用于查询日历文件夹的 URI 示例如下：

https://graph.microsoft.com/V1.0/users/[email protected]/calendar/calendarView?startDateTime=2024-04-08T00:00:00&endDateTime=2024-04-15T00:00:00

获取与报告期间匹配的日历事件后，脚本会提取详细信息，例如组织者的姓名和电子邮件地址、会议主题、开始和结束时间、持续时间（以分钟为单位）以及与会者人数。默认情况下，Exchange Online 将会议主题替换为组织者的姓名。这样做是为了在只能访问会议室日历的人员查看详细信息时保护会议的隐私（个别与会者可以看到有关会议的完整信息）。

存在一个有争议的情况，即在共享物理资源中安排的会议应该揭示会议组织者为活动提供的任何主题。如果您同意，您可以更新会议室邮箱的日历处理设置以保留会议主题。

处理室邮箱创建的输出是 HTML 报告（图 1）。每个房间可能不需要通过电子邮件发送提醒，因此此报告可作为总体摘要。

通过电子邮件发送每周时间表

最初的请求要求将每周的时间表发送到分发列表。第一个要解决的问题是如何存储通讯组列表的电子邮件地址以接收房间邮箱的更新。最简单的解决方案是将电子邮件地址存储在 15 个自定义属性之一中，该属性可供启用邮件的收件人使用，包括会议室邮箱。我选择使用CustomAttribute13。

以前，该脚本会获取房间邮箱的详细信息。此信息包括每个邮箱的主 SMTP 地址，但不包括用户主体名称或帐户标识符。虽然最佳实践是主 SMTP 地址和用户主体名称具有相同的值，但用户帐户比会议室邮箱更可能遵守该准则。因此，该脚本使用针对 Users API 的筛选查找来检索自定义属性集（称为 Entra ID 的 onPremisesExtensionAttributes）并提取 CustomAttribute13 的值。

$Uri = ("https://graph.microsoft.com/v1.0/users?`$filter=mail eq '{0}'&`$select=displayName,id,onPremisesExtensionAttributes" -f $Room.emailaddress)
        [array]$Data = Get-GraphData -Uri $Uri -AccessToken $Token
        If ($Data) {
            [array]$Attributes = $Data | Select-Object -ExpandProperty OnPremisesExtensionAttributes
            # Extract email address from custom attribute 13
            $EmailAddress = $Attributes.extensionAttribute13
        }

如果脚本找到电子邮件地址，它将构造并发送邮件消息。通常，我会使用 Microsoft Graph PowerShell SDK 中的 Send-MgUserMail cmdlet 来发送电子邮件，但此脚本使用 Graph 请求，因此它使用共享邮箱将 JSON 正文发布到 SendMail API发件人。代码如下：

$MsgSubject = ("Weekly Schedule for the {0} room from {1} to {2}" -f $Room.DisplayName, $StartDate, $EndDate)
$MsgBody = @{
   Content = "$($HtmlMsgBody)"
   ContentType = 'html'  
}
[array]$Recipient = @{
   emailAddress = @{address = $EmailAddress}
}  
$Message =  @{subject           = $MsgSubject}
$Message += @{toRecipients      = $Recipient } 
$Message += @{body              = $MsgBody}
$Params   = @{'message'         = $Message}
$Params  += @{'saveToSentItems' = $True}
$Params  += @{'isDeliveryReceiptRequested' = $True}
$Uri = ("https://graph.microsoft.com/v1.0/users/{0}/sendMail" -f $msgfrom)
$BodyParams = $Params | ConvertTo-Json -Depth 10
Invoke-RestMethod -Uri $Uri -Method POST -Body $BodyParams -Headers $Headers -ContentType 'application/JSON'

图 2 是发送的电子邮件示例，其中包含房间的每周时间表。

目标完成

该脚本是通过组装来自不同脚本的组件并调整结果而组合在一起的。 Copilot for GitHub 对于此类任务非常有用，因为它可以利用 GitHub 存储库中存储的大量 PowerShell 脚本。然而，生成式人工智能只能根据之前的情况生成代码。了解 Microsoft 365 的工作原理以及租户内可用数据的创新使用仍然是一项人类技能，我认为人工智能在未来相当长的一段时间内都无法掌握这一技能。