如何使用 Microsoft Graph PowerShell 创建邮箱规则

在本教程中，我将向您展示如何使用 Microsoft Graph PowerShell 在 Exchange Online 中创建邮箱规则。我将介绍完成任务所需的权限（委派权限和应用程序权限）、如何构建您自己的规则条件和操作以及如何在租户中的多个用户之间应用邮箱规则。

为了创建邮箱规则，我们将利用 Microsoft.Graph.Mail 模块中包含的 New-MgUserMailFolderMessageRule cmdlet。

先决条件和权限

首先，要运行我们的脚本和必要的命令，您必须安装 Microsoft Graph PowerShell SDK，请查看我的有关如何安装 Microsoft Graph PowerShell 模块的教程。

您还必须确保登录租户的用户拥有执行这些操作所需的权限，在大多数情况下，全局管理员权限即可。

如何使用 Microsoft Graph PowerShell 创建邮箱规则

现在让我们看看如何使用 Microsoft Graph PowerShell 在单个用户帐户中创建单个邮箱规则。我对下面的脚本进行了评论，以帮助您了解正在发生的事情。

在下面的脚本中，我们将创建一个邮箱规则，该规则适用于在发件人地址中包含特定字符串的发件人，并通过将其全部移动到特定文件夹来对这些电子邮件进行操作。

正如您所看到的，我们需要提供一些信息才能实现这一点。首先是我们想要应用规则的用户UPN，然后是目标文件夹名称、规则的显示名称以及发件人包含字段。

#Import the graph module
Import-Module Microsoft.Graph.Mail

#Connect to Microsoft Graph
Connect-MgGraph -Scope MailboxSettings.Read, MailboxSettings.ReadWrite, Mail.ReadWrite

#Complete the below with the requested information
$targetuser = "your UPN here"
$targetfolder = "Target folder name here"
$userid = $targetuser

#Store the target folder
$targetfolder = Get-MgUserMailFolder -UserId $userId -filter "DisplayName eq '$targetfolder'"

#Store the inbox folder (New rules can only be created on the inbox folder)
$MailboxFolder = Get-MgUserMailFolder -UserId $userId -filter "DisplayName eq 'inbox'"

#Define the Conditions and Actions
$params = @{
	DisplayName = "Company-Wide Move To Training Folder"
	Sequence = 2
	IsEnabled = $true
	Conditions = @{
		SenderContains = @(
			"[email "
		)
	}
	Actions = @{
		moveToFolder = $targetfolder.id
		StopProcessingRules = $true
	}
}

#Create the rule
New-MgUserMailFolderMessageRule -UserId $userId -MailFolderId $mailboxfolder.id -BodyParameter $params

脚本运行后，您应该看到如下所示的输出：

您还可以通过单击设置> 查看所有 Outlook 设置 > 规则.

这是另一个示例，我将只关注脚本的规则参数部分，因为这是最有可能发生变化的部分。在这里，我们指定电子邮件是否来自“[email ”并且主题字段中包含“Training”，然后将其移动到目标文件夹并将其标记为高重要性。

$params = @{
	DisplayName = "Company-Wide Move To Training Folder"
	Sequence = 2
	IsEnabled = $true
	Conditions = @{
		SenderContains = @(
			"[email "
		)
		SubjectContains = @(
			"Training"
		)
	}
	Actions = @{
		moveToFolder = $targetfolder.id
		markImportance = "high"
	}
}

如何以 JSON 格式构建自己的消息规则

如果您不想使用上面的示例，最好的办法就是构建自己的规则条件和操作，所以让我们看看如何构建自己的规则。

首先，让我们从基线开始，下面是我们定义的参数的主体，您可以看到条件和操作字段为空。我们还需要提供一些初始参数，例如 DisplayName、Sequence 编号和 IsEnabled （启用或禁用的位置..） 。

$params = @{
	DisplayName = "#DisplayName#"
	Sequence = 2 #supply a number
	IsEnabled = $true #true or false
	Conditions = @{
		#conditions
	}
	Actions = @{
		#Actions
	}
}

您可以在脚本的条件和操作字段中提供许多不同的参数，请查看下面的列表以了解可用的参数，

可选条件

• “bodyContains”：[“字符串”]
• “bodyOrSubjectContains”：[“字符串”]
• “类别”：[“字符串”]，“来自地址” ”：[{“@odata.type”：“microsoft.graph.recipient” }]
• “hasAttachments”：“布尔值”，“headerContains”: [“字符串”]
• “重要性”：“字符串”，“isApprovalRequest”: “布尔值”
• “isAutomaticForward”：“布尔值”
• “isAutomaticReply”：“布尔值”
• “isEncrypted”：“布尔值”
• “isMeetingRequest”：“布尔值”
• “isMeetingResponse”：“布尔值”
• “isNonDeliveryReport”：“布尔值”
• “isPermissionControlled”：“布尔值”
• “isReadReceipt”：“布尔值”
• “isSigned”：“布尔值”
• “isVoicemail”：“布尔值”
• “messageActionFlag”：“字符串”
• “notSentToMe”：“布尔值”
• “recipientContains”：[“字符串”]
• “senderContains”：[“字符串”]
• “敏感度”：“字符串”
• “sentCcMe”：“布尔值”
• “sentOnlyToMe”：“布尔值”
• “sentToAddresses”：[{“@odata.type”：“microsoft.graph.recipient”}]
• “sentToMe”：“布尔值”
• “sentToOrCcMe”：“布尔值”
• “subjectContains”：[“字符串”]
• “withinSizeRange”：{“@odata.type”： “microsoft.graph.sizeRange”}

可选操作

• “分配类别”：[“字符串”]
• “copyToFolder”：“字符串”
• “删除”：“布尔值”
• “forwardAsAttachmentTo”：[{“@odata.type”：“microsoft.graph.recipient”}]
• “forwardTo”：[{“@odata.type”：“microsoft.graph.recipient”}]
• “markAsRead”：“布尔值”
• “markImportance”：“字符串”
• “moveToFolder”：“字符串”
• “永久删除”：“布尔值”
• “redirectTo”：{“@odata.type”： “microsoft.graph.recipient”}
• “stopProcessingRules”：“布尔值”

要在脚本中包含各种类型的条件和操作，您可以通过以相关格式包含它们来实现。并非每个参数都以相同的格式指定，因此下面是一些示例。

示例： “copyToFolder”：“字符串”

当定位文件夹时，必须指定文件夹 ID。使用上面脚本中的示例来收集文件夹 ID。

copyToFolder = $targetfolder.id

示例： “markAsRead”：“布尔值”

由于这是一个布尔值，因此它可以是 True 或 False。

markAsRead: $true or $false

示例： “bodyOrSubjectContains”：[“字符串”]

虽然该值是“string”格式，但它被括在方括号中，这意味着当我们指定该参数时，它必须以数组形式呈现。

bodyContains = @(
			"important information"
		)

如何为所有用户创建邮箱规则

不幸的是，与我们将邮箱设置应用于我们自己的用户上下文时不同，在 Microsoft Graph PowerShell 中使用委派权限时，我们无法将邮箱设置应用于任何其他用户（这是我们在使用交互式登录提示时可以使用的唯一权限类型）。这是因为邮箱设置不是用户的属性，而是保存在邮箱配置中，无法通过委托权限进行访问。然而，MS Docs 中并没有明确说明这一点，因此请记住这一点。

为了实现我们的目标，我们首先需要在Azure AD中注册一个应用程序，然后为该应用程序提供必要的Graph权限。您可以选择使用客户端密钥或证书来向 365 进行身份验证，因此在我们的示例中，我们将使用密钥来简化流程。按着这些次序：

1. 首先使用全局管理员帐户登录 Azure AD https://aad.portal.azure.com/

2. 从左侧菜单中选择Azure Active Directory，然后选择应用注册。

3. 选择新注册。输入应用程序的名称，选择仅此组织目录中的帐户，然后输入重定向 URI（我刚刚使用过 office.com）。然后点击注册。

4. 记下概览选项卡上的应用程序（客户端）ID，因为我们在脚本中需要它。

5. 从左侧菜单中，选择 API 权限。

6. 单击添加权限，然后选择Microsoft Graph并单击应用程序权限。

7. 在搜索框中，找到并选择以下权限：

• 邮箱设置.ReadWrite
• 邮件阅读
• 用户.阅读.全部

然后点击添加权限。

8. 在应用程序注册页面上，选择授予管理员同意...，然后在弹出窗口中单击“是”。

9. 现在，在左侧菜单中，选择证书和机密。

10. 单击添加新密码，右侧将出现一个新窗口。输入说明和有效期，然后单击添加。

11. 创建密钥后，您将在应用程序注册页面上看到它。记下值和秘密 ID，因为我们在脚本中需要它们。

12. 最后，我们只需要获取租户 ID。我们可以通过返回 https://aad.portal.azure.com/ 并从左侧菜单中选择 Azure Active Directory 来完成此操作。租户 ID 将在“概述”选项卡上列出。

完整脚本

以下是完整的脚本，它将把您的邮箱规则部署到 Microsoft 365 租户中的所有用户。

#Import Module
Import-Module Microsoft.Graph.Mail

#Store connection information
$appid = 'YOUR APPLICATION ID'
$tenantid = 'YOUR TENANT ID'
$secret = 'YOUR CLIENT SECRET >VALUE<'
 
#Store request body
$body =  @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    Client_Id     = $appid
    Client_Secret = $secret
}

#Sent HTTPs request to Microsoft 
$connection = Invoke-RestMethod `
    -Uri https://login.microsoftonline.com/$tenantid/oauth2/v2.0/token `
    -Method POST `
    -Body $body
 
#Store access token
$token = $connection.access_token
 
#Connect to Microsoft Graph
Connect-MgGraph -AccessToken $token

#Define target folder
$targetfolder = "Folder where you want to move mail to"

#Store all users
$allusers = get-mguser -Property UserType, Displayname, Id, Mail, UserPrincipalName | where-object {$_.UserType -eq "Member"}

#Apply rule to all users
ForEach ($user in $allusers) {

#Null variables
$vtargetfolder = $null
$MailboxFolder = $null

#Store targer and inbox folder
$vtargetfolder = Get-MgUserMailFolder -UserId $user.Id -filter "DisplayName eq '$targetfolder'"
$MailboxFolder = Get-MgUserMailFolder -UserId $user.id -filter "DisplayName eq 'inbox'"

#Check if Target folder exists
If ($vtargetfolder -eq $null) {
write-host "Folder:" $targetfolder " is missing for" $user.DisplayName
} else{

#Define rule conditions and actions
$params = @{
	DisplayName = "Company-Wide Move To Training Folder"
	Sequence = 2
	IsEnabled = $true
	Conditions = @{
		SenderContains = @(
			"[email "
		)
	    }
	Actions = @{
		moveToFolder = $targetfolder.id
		StopProcessingRules = $true
	    }
    }
    
    #Create new rule
    New-MgUserMailFolderMessageRule -UserId $user.id -MailFolderId $mailboxfolder.id -BodyParameter $params | out-null
    Write-host "Mailbox rule created successfully for" + $user.DisplayName
    }
}