将适用于 PowerShell 的 Microsoft Graph SDK 与 Azure 自动化结合使用

从操作手册到电子邮件

在上一篇有关将 Azure 自动化帐户和 Runbook 与 Exchange Online 管理 PowerShell 模块一起使用的文章中，我还解释了如何在 Runbook 中执行的 PowerShell 脚本中使用图形 API 查询。自然的后续问题是询问 Microsoft Graph PowerShell SDK 是否支持 Runbook。我可以报告说，该 SDK 可以使用基于证书的身份验证或托管标识与 Azure 自动化一起使用。当然，一个简单的陈述可能隐藏着一堆复杂性，所以让我们来探讨一下细节。

作为可能性的实际示例，在本文中，我将转换脚本以将电子邮件发送到此处描述的新邮箱，以便在 Runbook 中执行。

Azure 自动化设置

正如上一篇文章中所讨论的，我们将使用 Azure 自动化帐户（与 Azure 订阅绑定）在沙箱服务器上运行脚本。 Azure 自动化支持托管标识，我将在以后的文章中深入探讨该主题。目前，经过尝试和测试的技术可以完成这项工作。

更新：Azure 自动化不再支持 Runbook 帐户。请改用托管身份。请参阅本文了解更多信息。 此处解释的将模块加载到自动化帐户以及为自动化帐户分配图形权限的原则仍然有效。

导入图形模块

RunAs 帐户具有由 Azure 管理的服务主体和证书。这些是用于身份验证的关键组件。然而，身份验证仅仅是开始。为了使 Microsoft Graph PowerShell SDK 可用于 Runbook，我们必须将其模块作为共享资源导入到自动化帐户中。

您可能会注意到我使用的是模块而不是模块。当您从 PowerShell 库下载 Microsoft Graph PowerShell SDK 并将其安装在工作站上时，您不会获得任何模块。相反，SDK 分为许多不同的模块，每个模块负责整个 Graph 景观的一小部分。当您将SDK导入自动化账户时，您必须导入脚本所需的模块。第一个任务是检查您计划使用的 cmdlet 的文档，以发现每个 cmdlet 所在的模块。

例如，假设您的脚本使用 Get-MgOrganization cmdlet 返回租户的详细信息。 Microsoft 的文档告诉我们，该 cmdlet 属于 Microsoft.Graph.Identity.DirectoryManagement 模块（图 1）。

顺便说一句，SDK cmdlet 的文档是一个可怕的例子，说明了为什么人工智能有时在用于基于源代码创建文档时效果不佳。改进文档将帮助人们更好地理解 SDK cmdlet 并鼓励他们使用。目前，需要大量的解释和极大的耐心。

将 SDK 模块加载到 Azure 自动化帐户中

检查脚本找到所有 SDK cmdlet 后，我最终导入了四个模块（图 2）：

• Microsoft.Graph.Authentication：针对 Graph 进行身份验证。
• Microsoft.Graph.Users.Action：发送消息。
• Microsoft.Graph.Mail：访问邮件消息。
• Microsoft.Graph.Identity.Management：获取组织详细信息。

分配图表权限

加载 SDK 模块以与图表交互是我们的起点：拥有这样做的权限就完成了这个循环。当您使用 Connect-MgGraph cmdlet 进行连接时，您创建的会话可以使用某些图形权限。这是会话范围。在这种情况下，脚本需要访问用户的邮箱来创建消息，然后再将其发送给消息收件人，因此用于身份验证的实体必须拥有执行这些操作所需的图形应用程序权限。该实体是 RunAs 帐户的服务主体。在脚本可以发送电子邮件之前，管理员必须授予同意以允许服务主体拥有 Mail.Send 和 Mail.ReadWrite 权限。

为 RunAs 帐户的服务主体分配权限与为注册的应用程序分配权限相同。转到 Azure AD 管理中心，在注册的应用程序集中找到服务主体，添加必要的权限，并代表组织授予同意。您最终应该得到如图 3 所示的结果。存在两个额外的图形权限，因为我在上一篇文章中使用了此服务主体。

请注意不要创建具有太多图形权限的服务主体。与用于与 Microsoft Graph PowerShell SDK 进行交互会话的服务主体一样，如果服务主体用于多个任务，那么随着时间的推移，服务主体很容易积累权限。在生产中，考虑对不同的作业使用单独的自动化帐户。

修改PowerShell代码

我们现在拥有一个具有正确权限和所需模块访问权限的 RunAs 帐户，因此是时候编写一些代码了。工作脚本可作为起点，但需要调整才能在 Runbook 中工作。这是我所做的：

首先，我添加了一个新的身份验证部分以从自动化帐户获取证书指纹。然后，该证书将对与 Microsoft Graph 的连接进行身份验证。

$Connection = Get-AutomationConnection -Name AzureRunAsConnection
# Get certificate from the automation account
$Certificate = Get-AutomationCertificate -Name AzureRunAsCertificate
# Connect to the Graph SDK endpoint using the automation account
Connect-MgGraph -ClientID $Connection.ApplicationId -TenantId $Connection.TenantId -CertificateThumbprint $Connection.CertificateThumbprint

接下来，我检索租户服务域并将其与相同的证书指纹一起使用以连接到 Exchange Online（以获取最近添加的邮箱集）。

$Organization = Get-MgOrganization
$TenantName = $Organization.DisplayName
$TenantDomain = $Organization.Verifieddomains | ? {$_.IsInitial -eq $True} | Select -ExpandProperty Name
# Connect to Exchange Online
Connect-ExchangeOnline –CertificateThumbprint $Connection.CertificateThumbprint –AppId $Connection.ApplicationID –ShowBanner:$false –Organization $TenantDomain

请记住，自动化帐户需要一些权限才能连接到 Exchange Online。这些权限在我的上一篇文章中进行了描述。

然后我定义了消息的发件人（我想使用的邮箱）。当我以交互方式运行脚本时，我从当前连接到 PowerShell 的帐户获取此信息，但这对于 RunAs 帐户不起作用，因此我们需要定义要在变量中使用的帐户的 SMTP 地址。

$MsgFrom = "WelcomeNewUsers@Office365itpros.com"

我的脚本附加了存储在本地驱动器上的欢迎信。显然，在沙箱中运行的脚本无法访问我的本地驱动器，因此我从网站下载欢迎信并将其存储在本地文件夹中。然后，该脚本对内容进行编码，以允许将文件附加到消息中。

$WebAttachmentFile = "https://office365itpros.com/wp-content/uploads/2022/02/WelcomeToOffice365ITPros.docx"
New-Item -Path c:\TempForScriptxxx -ItemType directory -ErrorAction SilentlyContinue
$AttachmentFile = "c:\TempForScriptxxx\WelcomeNewEmployeeToOffice365itpros.docx"
Invoke-WebRequest -uri $WebAttachmentFile -OutFile $AttachmentFile
$Attachment = (Get-Item -Path $AttachmentFile).Name
$EncodedAttachmentFile = [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentFile))

最后。我删除了使用 Write-Host 发送到屏幕的所有消息。发出这些消息是没有意义的，因为在 Runbook 中执行代码时没有屏幕可以显示这些消息。

消息到达

就是这样。准备工作完成后，过程并不困难。该代码之所以能够运行，是因为该帐户中所有必需的模块都可用，并且该帐户具有正确的 Graph 权限，因此邮件会流入新用户的邮箱（图 4）。

您可以从 GitHub 下载我使用的完整脚本的副本。

自动化很好

使用 Azure 自动化的好处是，您可以发布脚本，然后安排它每周运行，以向前一周加入的用户发送欢迎消息。只需点击几下，新加入者就会收到一波又一波的快乐。创建和发送电子邮件的相同技术可用于分发许多其他作业生成的信息。这不是一件好事吗？