使用 Microsoft Graph PowerShell SDK 发送 Exchange Online 电子邮件

探索 Graph PowerShell SDK

最近，我一直在探索如何将 Microsoft Graph 与 PowerShell 结合使用来自动执行一些常见的 Microsoft 365 管理任务，例如如何发送 Exchange Online 邮件来报告脚本的结果。最近促使我考虑在 PowerShell 中使用 Graph API 的因素包括：

• 微软决定在 2022 年迁移到新的许可平台，这意味着某些 Azure AD cmdlet 在 2022 年 6 月 30 日之后将无法运行。（微软随后将某些租户的截止日期延长至 2023 年 3 月）。
• 这项有充分根据的活动旨在从 2023 年 1 月 1 日起取消对 Exchange Online 连接协议的基本身份验证的支持。尽管 Microsoft 目前已免除 SMTP AUTH 协议，但明智的做法是准备考虑 PowerShell 的 Send-Message cmdlet 的替代方案，例如 Graph SendMail API。

我使用适用于 PowerShell 的 Microsoft Graph SDK 来解决第一个问题，并使用本机 Graph API 调用来解决第二个问题。在本文中，我将通过使用 SDK 中的 New-MgUserMessage 和 Send-MgUserMessage cmdlet 来解释 Send-MailMessage cmdlet 的第二种替代方案创建并向新员工发送欢迎信息。

欢迎电子邮件

作为入职流程的一部分，组织通常会向新员工发送欢迎电子邮件。该电子邮件通常包含有关在组织中工作的有用提示以及新员工需要了解的事情，例如如何找到自助餐厅。为了自动化该过程，该脚本执行以下操作：

• 连接到 Exchange Online 以查找过去 7 天内添加的员工的邮箱。
• 连接到 Microsoft Graph 以创建和发送电子邮件。与图表的所有连接一样，您需要访问数据的权限。在本例中，我们需要 Mail.Send 和 Mail.ReadWrite 权限。该脚本以交互方式运行，因此我们需要了解用于连接到图的服务主体的权限蔓延。
• 对于找到的集合中的每个邮箱，使用 New-MgUserMessage cmdlet 在登录用户的邮箱中创建 HTML 邮件。
• 使用 Send-MgUserMessage cmdlet 发送消息。

该脚本很基本（您可以从 GitHub 下载），但足以证明其原理。您可以通过添加附件（可能是新员工指南）或更改收件人组来修饰它。我们稍后会讨论这些要点。

连接代码

连接到图表的代码很简单：

Connect-MgGraph -TenantId a562313f-14fc-43a2-9a7a-d2e27f4f3478 -Scope "Mail.Send, Mail.ReadWrite"
$Details = Get-MgContext
$Scopes = $Details | Select -ExpandProperty Scopes
$Scopes = $Scopes -Join ", "
$ProfileName = (Get-MgProfile).Name
$TenantName = (Get-MgOrganization).DisplayName

Connect-MgGraph cmdlet 使用租户标识符连接到租户（确保为租户使用正确的值）并请求我们需要的两个权限。如果 Graph SDK 使用的服务主体尚未同意这些权限，则 Graph 会提示您同意。其他命令获取登录上下文和组织名称的详细信息。

寻找目标邮箱

查找目标邮箱的代码会查找过去 7 天内创建的所有邮箱。同样，这非常简单：

[string]$CheckDate = (Get-Date).AddDays(-7)
# Find all mailboxes created in the target period
[array]$Users = (Get-ExoMailbox -Filter "WhenMailboxCreated -gt '$CheckDate'" -RecipientTypeDetails UserMailbox -ResultSize Unlimited -Properties WhenMailboxCreated | Select WhenMailboxCreated, DisplayName, UserPrincipalName, PrimarySmtpAddress)
If ($Users -eq $Null) { Write-Host ("No mailboxes found that were created before {0}. Exiting!" -f $CheckDate) }

创建并发送消息

找到目标邮箱集后，我们可以循环访问每个邮箱以创建自定义 HTML 消息（图 1），并填充 Send-MgUserMessage cmdlet 发送新消息所需的消息属性集给收件人。

# Create and send welcome email message to each of the new mailboxes
ForEach ($User in $Users) {
      # Add the recipient using the mailbox's primary SMTP address
      $EmailAddress  = @{address = $User.PrimarySmtpAddress} 
      $EmailRecipient = @{EmailAddress = $EmailAddress}  
      Write-Host "Sending welcome email to" $User.DisplayName
      # Customize the message 
      $htmlHeaderUser = "<h2>New User " + $User.DisplayName + "</h2>"    
      $htmlbody = $htmlheaderUser + $htmlline1 + $htmlline2 + $htmlline3 + "<p>"
      $HtmlMsg = "</body></html>" + $HtmlHead + $HtmlBody
      # Construct the message body
      $MessageBody = @{
           content = "$($HtmlBody)"
           ContentType = 'html'
           }
     # Create a draft message in the signed-in user's mailbox
     $NewMessage = New-MgUserMessage -UserId $MsgFrom -Body $MessageBody -ToRecipients $EmailRecipient -Subject $MsgSubject
     # Send the message
     Send-MgUserMessage -UserId $MsgFrom -MessageId $NewMessage.Id  
} # End ForEach User

与许多其他 PowerShell cmdlet（尤其是 Exchange Online 的 cmdlet）不同，当您与 Graph API 交互时，必须非常小心地使用 API 所需的任何输入格式。例如，您可以想象应该可以获取目标邮箱的主 SMTP 地址并使用该字符串将收件人添加到邮件中。不幸的是，情况并非如此，您需要使用正确格式的元素构建一个数组，然后图表才会满意。

处理收件人

上面的代码显示了添加单个 TO: 收件人的步骤。如果您想添加其他收件人，则需要执行相同的操作来构建输入数组。例如，假设您想要向邮件添加几个密件抄送收件人。我们在数组中声明收件人（或使用 PowerShell 从某个来源获取它们）：

$BCCRecipients = @("[email protected]", "[email protected]")

然后构建输入数组：

$BCC = $BCCRecipients | % {@{emailAddress = @{ address = $_ }}}

该数组看起来像：

$BCC

Name                           Value
----                           -----
emailAddress                   {address}
emailAddress                   {address}

我们可以使用以下命令查看数组的值：

$BCC.Values

Name                           Value
----                           -----
address                        [email protected]
address                        [email protected]

SDK 开发人员可以更轻松地将收件人添加到消息中，从而为我们所有人带来好处。我确信消息结构需要嵌套值是有逻辑的，但这并不容易说服人们更新代码以使用 SDK。

添加附件

向消息添加附件是 SDK 开发人员可以向 PowerShell 开发人员隐藏一些复杂性的另一个地方。目前，添加附件需要您创建文件的 Base64 编码版本并将其包含在输入数组中。例如：

$AttachmentFile = "c:\temp\WelcometoOffice365ITPros.docx"
$EncodedAttachmentFile = [convert]::ToBase64String((Get-Content $AttachmentFile -Encoding byte)) 
$MsgAttachment = @{
    "@odata.type"= "#microsoft.graph.fileAttachment"
    name = ($AttachmentFile -split '\')[-1]
    contentBytes = $EncodedAttachmentFile
}

我们刚刚构建的输入数组如下所示：

$MsgAttachment

Name                           Value
----                           -----
contentBytes                   UEsDBBQABgAIAAAAIQD7xliMzwEAAEoKAAATAAgCW0NvbnRlbnRfVHlwZXNd…
name                           WelcometoOffice365ITPros.docx
@odata.type                    #microsoft.graph.fileAttachment

要在消息中包含附件，请将数组指定为 New-MgUserMessage 的 Attachments 参数的输入。附件将按您的预期显示（图 2）。

$NewMessage = New-MgUserMessage -UserId $MsgFrom -Body $MessageBody -ToRecipients $EmailRecipient -Subject $MsgSubject -Attachments $MsgAttachment

良好的功能性；可以更容易

有时政客在恳求连任时会声称他们已经做了很多事情，但仍有很多事情要做。对于使用 Microsoft Graph SDK for PowerShell 通过 Exchange Online 创建和发送消息，我也有同样的感觉。有很多可用的功能，但对于不懂的人来说很难访问，特别是当来自相对简单的 Send-MailMessage cmdlet 时。缺乏良好的文档是另一个障碍。

如今，适用于 PowerShell 的 Microsoft Graph SDK 模仿了底层 Graph API 的工作方式。考虑到发展的早期阶段，这是适当和必要的。但为了说服人们接受和使用 SDK，我认为开发人员需要让管理员更简单地通过 SDK cmdlet 访问 Graph 的功能。