掌握 Microsoft 365 PowerShell 脚本编写

---

做好 Microsoft 365 PowerShell 的三个基础知识，脚本编写就容易多了

你们中有些人可能知道，我编写了很多 PowerShell。我不是一个很好的 PowerShell 开发人员。我的大部分代码都忽略了错误处理等基础知识，因为我编写脚本是为了探索和解释完成工作的原则，而不是开发完整的解决方案。无论如何，这都是我的借口。

在亚特兰大举行的 TEC 2023 会议上，我被问及如何为 Microsoft 365 编写 PowerShell 脚本。我越多地使用 PowerShell 与 Microsoft 365 工作负载交互，我就越确信管理员的 PowerShell 知识的本质可归结为三个事物：

• 获取对象。
• 解释物体。
• 报告对象。

95% 的脚本遵循获取、解释和报告的模式。这适用于交互式运行的脚本和按计划运行的脚本，例如 Azure 自动化 Runbook。当然，可能需要一些调整来更新邮箱设置等内容，但一般来说，我的脚本遵循该模式。我相信，如果管理员很好地学习了执行该模式的基础知识，他们将充分掌握 PowerShell 来处理复杂的自动化项目。让我解释一下我为什么这么想。

获取对象

在许多情况下，之所以需要自动化，是因为需要对一组对象（例如邮箱、站点或团队）执行某些操作。脚本可能首先运行 Connect-MgGraph 或 Connect-ExchangeOnline 之类的 cmdlet 连接到不同的 Microsoft 365 终结点，然后初始化一些变量，但第一个真正的工作是在获取时完成的用于处理的对象。

所有 Microsoft 365 模块都配备了用于获取对象的 cmdlet。有时存在多个可以获取相同对象的 cmdlet，这意味着技巧是正确选择要使用的 cmdlet。该决定取决于具体情况。我们稍后会讨论这个问题。

表 1 列出了 Microsoft 365 中使用的一些基本对象以及可用于获取这些对象的 cmdlet。

Object typeCmdletsModuleUser accountsGet-MgUserMicrosoft Graph PowerShell SDKMailboxesGet-Mailbox and Get-ExoMailboxExchange Online managementSharePoint Online sitesGet-SPOSite Get-MgSiteSharePoint Online management Microsoft Graph PowerShell SDKOneDrive for Business accountsGet-SPOSite Get-MgSiteSharePoint Online management Microsoft Graph PowerShell SDKMicrosoft 365 GroupsGet-UnifiedGroup Get-MgGroupExchange Online management Microsoft Graph PowerShell SDKTeamsGet-Team Get-MgTeamMicrosoft Teams Microsoft Graph PowerShell SDKDevicesGet-MgDeviceMicrosoft Graph PowerShell SDK

从表 1 中可以看出，Microsoft Graph PowerShell SDK cmdlet 可以访问大多数重要的 Microsoft 365 对象。邮箱是明显的例外。 SDK cmdlet 可用于与消息交互，但只能通过用户端点进行交互。例如，您无法使用 SDK cmdlet 获取共享邮箱或房间邮箱。

过滤和限制

如果没有达到限制，获取某种类型的每个对象相对简单。 Microsoft 365 在不同的地方应用限制，以确保用户无法吸收过多的资源。 PowerShell 也不例外。您当然可以使用单个命令获取许多对象，但一般规则是仅检索您想要处理的内容。

例如，请勿在没有过滤器的情况下运行 Get-ExoMailbox cmdlet，因为您最终会得到用户邮箱、共享邮箱和会议室邮箱的集合。相反，请指定RecipientTypeDetails参数来查找所需的邮箱类型。更好的是，添加一个过滤器以进一步关注所需的精确对象集。格式良好的查询看起来像这样：

[array]$Mailboxes = Get-ExoMailbox -Filter {Office -eq "Dublin"} -RecipientTypeDetails UserMailbox -ResultSize Unlimited

该命令告诉 PowerShell 创建符合两个条件的邮箱数组：它们的 Office 属性设置为 Dublin 并且它们是用户邮箱。该命令愿意接受所有匹配的邮箱。 Exchange 支持不同 cmdlet 的不同可过滤属性，但您会发现经常使用相同的属性。

同样，一个常见的要求是找到具有许可证的 Entra ID 用户帐户集。查找许可帐户会删除为共享邮箱、Microsoft Bookings 和类似目的创建的用户帐户。此命令使用 Get-MgUser cmdlet 来完成这项工作：

[array]$Users = Get-MgUser -Filter "assignedLicenses/`$count ne 0 and userType eq 'Member' and OfficeLocation eq 'Dublin'" -ConsistencyLevel eventual -CountVariable Records -All

该命令创建一组拥有许可证且其 OfficeLocation 属性为 Dublin 的用户帐户。由于过滤器查询多值属性，因此称为复杂查询。在 Entra ID 术语中，这意味着查询必须等到所有数据副本都一致为止（这就是存在 Consistencylevel 参数的原因）。

很明显，Get-ExoMailbox 和 Get-MgUser cmdlet 使用不同类型的过滤器。 Exchange cmdlet 源于主要 Microsoft 服务器产品 (Exchange Server 2007) 中 PowerShell 的首次实现，并且它们遵循当时制定的语法规则。 Graph SDK cmdlet 复制 Graph API 查询规则，并解释了这些示例中看到的不同语法。

尽管如此，黄金法则仍然是只获取需要处理的数据。使用好的过滤器是实现这一目标的最佳方法。

解释对象

找到一些对象后，下一步就是理解数据。大多数 PowerShell cmdlet 返回易于使用的属性，但某些 Microsoft 365 cmdlet 需要注意一些事项。

在某些情况下，属性返回的值是一个数组，需要进行一些工作才能获取您可能需要的完整信息。考虑这个查找谁管理通讯组列表的示例：

Get-DistributionGroup -Identity VIPusers | Format-List ManagedBy

ManagedBy : {tony.redmond, Lotte.Vetler, d36b323a-32c3-4ca5-a4a5-2f7b4fbef31c}

ManagedBy 属性保存每个所有者帐户的名称。要获取有关所有者的更多信息，请将名称与另一个 cmdlet 结合使用，例如 Get-ExoMailbox。例如：

[array]$ManagedBy = Get-DistributionGroup -Identity VIPUsers | Select-Object -ExpandProperty ManagedBy

$ManagedBy | Get-ExoMailbox | Format-Table DisplayName, Alias, Name

DisplayName         Alias        Name
-----------         -----        ----
Tony Redmond        Tony.Redmond tony.redmond
Lotte Vetler        Lotte.Vetler Lotte.Vetler
Kim Akers (She/Her) Kim.Akers    d36b323a-32c3-4ca5-a4a5-2f7b4fbef31c

一些 Microsoft Graph PowerShell SDK cmdlet 掩盖了有价值的信息。例如，Get-MgGroupMember cmdlet 返回组成员的帐户标识符列表：

Get-MgGroupMember -GroupId (Get-MgGroup -Filter "Displayname eq 'System Innovation'").Id

Id                                   DeletedDateTime
--                                   ---------------
eff4cd58-1bb8-4899-94de-795f656b4a18
a3eeaea5-409f-4b89-b039-1bb68276e97d
67105a51-e817-493e-8094-f600babf5f62
d36b323a-32c3-4ca5-a4a5-2f7b4fbef31c

如果您需要组成员的详细信息，则需要采用不同的方法从 additionalProperties 属性中检索信息：

$GroupId = (Get-MgGroup -Filter "displayName eq 'System Innovation'").Id
Get-MgGroupMember -GroupId $GroupId | Select-Object -ExpandProperty additionalProperties

Key               Value
---               -----
@odata.type       #microsoft.graph.user
businessPhones    {+1 713 633-5141}
displayName       Kim Akers (She/Her)
givenName         Kim
jobTitle          VP Marketing
mail              [email protected]
mobilePhone       +1 761 504-0011
officeLocation    NYC
preferredLanguage en-US
surname           Akers
userPrincipalName [email protected]

在你问之前，图形就是以这种方式返回数据的。

统一审核日志是有关 Microsoft 365 租户内谁做了什么以及何时做了什么的宝贵信息的重要来源。当人们与应用程序交互时，工作负载捕获审核事件，这些事件最终会记录在审核日志中。 Search-UnifiedAuditLog cmdlet（最近出现了一些问题）从日志中查找数据。许多有趣的细节包含在名为 AuditData 的 JSON 格式属性中。在从该属性中提取信息之前，必须将其从 JSON 转换。

例如，此命令搜索审核日志以查找与 SharePoint Online 中的文件编辑相关的事件：

$Records = search-UnifiedAuditLog -StartDate 18-Oct-2023 -EndDate 19-Oct-2023 -Operations FileModified -Formatted -ResultSize 5000 -SessionCommand ReturnLargeSet

找到正确的事件后，我们可以转换其 AuditData 属性：

$AuditData = $Records[0].AuditData | ConvertFrom-Json

然后属性中的所有字段都可以在脚本中使用。例如，以下是修改后的文档的站点 URL：

$AuditData.SiteUrl
https://office365itpros.sharepoint.com/sites/BlogsAndProjects/

此时，您可能想知道如何处理可能遇到的所有边缘情况。反复试验和良好的互联网搜索是正常的反应。有人可能遇到并解决了您遇到的问题，也许 Practical365.com 上的一篇文章可以提供帮助。只要坚持下去。

报告对象

最终，脚本提取所有必需的数据，然后生成某种形式的报告。使脚本生成的输出可供人们使用的一些常见方法包括：

• 创建 HTML 格式文档并打印它或将文件存储在 SharePoint Online 中。
• 通过电子邮件分发报告、将数据插入消息正文或将其添加为附件。
• 将信息发布到 Teams 频道。
• 更新 SharePoint Online 网站中的列表。

这些动作标志着脚本的最后阶段。在脚本可以发布、发送或存储任何内容之前，从对象检索的数据必须保存在 PowerShell 对象（通常是数组或列表）中。

我使用相同的方法在所有脚本中记录数据。首先，我创建一个 PowerShell 列表：

$Report = [System.Collections.Generic.List[Object]]::new()

然后，在脚本处理对象后，通过填充自定义对象的属性并将其写入列表来处理要捕获的数据。从性能角度来看，这种方法比向数组添加项目更好，因为 PowerShell 会为每次添加重新创建数组。对于几个项目来说这还可以，但当处理数千个项目时就不太好了。更新列表很简单。例如：

$ReportLine = [PSCustomObject]@{
     TimeStamp       = $M.Received
     Sender          = $M.SenderAddress
     Recipient       = $M.RecipientAddress
     Subject         = $M.Subject
     Status          = $M.Status
     Direction       = $Direction
     SenderDomain    = $SenderDomain
     RecipientDomain = $RecipientDomain
    }
$Report.Add($ReportLine)

输出列表易于使用并且易于转换为其他形式。例如，要将数据包含在 HTML 文件中，脚本可以像这样转换列表：

$HTMLData = $Report | ConvertTo-HTML -Fragment

有关 Microsoft 365 PowerShell 的更多信息需要了解

在这里，我们实际上只触及了学习如何通过 PowerShell 使用 Microsoft 365 数据的皮毛。我希望我已经传达了我的坚定信念：编写成功的 PowerShell 脚本通常是通过遵循获取、处理和报告对象的公式来完成的。之后，就是完善基础知识的问题了。然后，阅读人们如何使用 PowerShell 解决自动化问题并理解他们的代码。

希望您会发现我们发布的许多有关使用 PowerShell 完成实际工作的 Practical365.com 文章对您有所帮助。如果您想浏览代码，请随意浏览我的 GitHub 存储库。您甚至可能在那里找到一些工作代码。