如何使用 PowerShell 创建计划任务

学习使用 PowerShell 在 Planner 计划中创建和更新任务

跟踪 Microsoft 对 Microsoft 365 工作负载所做的更改的最有用方法之一是将消息中心通知从 Microsoft 365 管理中心同步到 Planner。这种将更新帖子同步到 Planner 的功能首次出现于 2020 年，从那时起我就一直在使用它。尽管同步很容易设置和配置并且通常运行良好，但我认为使用 PowerShell 和 Microsoft Graph PowerShell SDK 中的 cmdlet 复制同步将是一个很好的学习挑战。

本文介绍了我使用 Graph SDK 将发布到 Microsoft 365 管理中心的通知同步为 Planner 计划中的任务的经验。这里探讨的概念和技术可用于更新任何 Planner 计划。如果您的账户是拥有目标计划的组的成员，则可以在交互式 Graph SDK 会话中运行该脚本。如果没有，您将必须使用已注册 Entra ID 应用程序的应用程序权限，并使用客户端密钥或 X.509 证书进行身份验证。

同步101

基本思想是：

• 定义目标计划。
• 查找新的公告项目。
• 为目标计划中的公告项创建新任务。

我想给我的同步版本添加一些标准版本不支持的花哨功能，所以我添加了：

• 自动将任务分配给指定的团队成员。
• 自动更新带有标签的任务（Planner 支持每个计划最多 25 个不同的标签）。
• 为每项任务添加目标日期。

让我们看看这些步骤是如何展开的。

定义目标计划

为了简单起见，该脚本为目标组和计划定义了两个变量。目标组（拥有该计划）由其组标识符定义。目标计划由其显示名称定义：

$GroupId = '78b47932-b35f-4b26-94c2-3228cb234b07'
$TargetPlanName = 'Admin Task Assignment'

查找新的 Microsoft 365 消息中心通知

消息中心通知称为服务公告消息，是服务运行状况和通信图 API 的一部分。用于检索服务公告消息的 SDK cmdlet 是 Get-MgServiceAnnouncementMessage。使用此 cmdlet 的另一个示例是计算 Microsoft 发布的有多少公告最终由于某种原因被延迟。

此代码显示脚本如何获取服务公告，然后过滤项目以查找开始日期大于检查日期的项目。从逻辑上讲，为了确保同步正常工作，检查日期应该是上次运行的日期。

[array]$AllAnnouncements = Get-MgServiceAnnouncementMessage -Sort 'LastmodifiedDateTime desc' -All 
[array]$AnnouncementsForPeriod = $AllAnnouncements | Where-Object {$_.StartDateTime -as [datetime] -gt $CheckDate} 
If ($AnnouncementsForPeriod.Count -eq 0) {
    Write-Host ("No new message center posts found since {0} - exiting" -f $CheckDate)
    Break
} Else {
    Write-Host ("{0} message center posts found to process..." -f $AnnouncementsForPeriod.count)
}

脚本中的下一步创建或更新任务。我们很快就会回来讨论这是如何发生的。

自动分配给计划成员

为了简单起见，我们假设某个计划属于 Microsoft 365 组。该组的成员也是可以被分配任务的计划成员。该脚本通过为其期望处理的每个服务公告类别定义一个受让人来实现此目的。类别包括 Exchange、Teams、SharePoint、Viva 等。通过查找 Get-MgGroup 返回的成员资格信息中列出的计划成员来进行分配。这为我们提供了一个成员显示名称，我们可以将其与 Get-MgUser 一起使用来返回完整的用户对象，包括用于分配任务的对象标识符（GUID）。

$SharePointAssignee = $PlanMembers.additionalProperties | Where-Object mail -match '[email protected]'
$SharePointAssignee = (Get-MgUser -UserId $SharePointAssignee.userPrincipalName) | Select-Object -First 1

随后，该脚本使用 Switch 语句来解释服务公告中描述的服务，以将责任分配给组成员。如果一切正常，脚本应该为 SharePoint Online 的任何公告创建一个任务，并将其分配给 SharePoint 受让人。

自动分配标签

如前所述，一个计划最多可以使用 25 个标签。每个标签都有一种颜色和指定的显示名称（默认情况下为颜色），可以自定义这些名称以在计划中使用。当标准同步运行时，它不会为其创建的任务分配标签。在脚本执行此操作之前，需要有人定义标签（在创建任务对话框中轻松完成），并且我们需要在脚本中包含有关标签的详细信息。

Planner GUI 仅显示带有为计划设置的任何自定义名称的标签。要发现标签编号，我们需要以计划的categoryDescriptions设置为例。查找此信息的方法如下：

$Uri =("https://graph.microsoft.com/beta/planner/plans/{0}/details" -f $TargetPlan.id)
$Data = Invoke-MgGraphRequest -Uri $Uri -Method GET
$Data.Categorydescriptions

Name                           Value
----                           -----
category17                     Microsoft Viva
category7                      SharePoint Online
category6                      Microsoft 365 Apps

例如，这告诉我们要将 SharePoint Online 的标签应用到任务，我们需要包含对 Category7 的引用，依此类推。在任务的属性中，appliedCategories 属性包含分配给该任务的标签。一个任务最多可以有 25 个标签，但脚本仅分配与为任务选择的存储桶匹配的标签。

创建任务

在脚本创建新任务之前，必须使用新任务的设置填充多个哈希表。该脚本使用哈希表用于：

• 任务参数。
• 作业。
• 标签。
• 描述（任务正文包含有关任务详细信息的自由文本描述）。该脚本执行一些处理以从服务公告中包含的正文中删除 HTML 标记。它还在描述顶部添加了一些详细信息，这些详细信息出现在定期同步创建的任务中。这些详细信息包括消息中心标识符（例如 MC712150）、发布日期和上次更新日期、类别和标签（图 1）。

创建新任务是通过运行 New-MgPlannerTask cmdlet 来完成的。新任务的所有参数都在哈希表中指定。这是涉及创建新任务的代码片段。

$TaskParameters = @{}
    $TaskParameters.Add('planId',$TargetPlan.Id)
    $TaskParameters.Add('bucketid',$TargetBucket)
    $TaskParameters.Add('title', $TaskTitle)
    $TaskParameters.Add('assignments', $TaskAssignments)
    $TaskParameters.Add('priority', '5')
    $TaskParameters.Add('startDateTime', $Announcement.LastModifiedDateTime)
    $TaskParameters.Add('details',$TaskDescription)
    $TaskParameters.Add('appliedCategories', $TaskLabels)
    # If an end date is given, use it as the due date for the task
    If ($Announcement.EndDateTime) {
        $TaskParameters.Add('dueDateTime', $Announcement.EndDateTime)
    }
    
    $NewTask = New-MgPlannerTask -BodyParameter $TaskParameters

当 Planner 检测到创建新任务时，它会自动向任务受让人发送电子邮件，告诉他们有新任务（图 2）。使用 Planner 浏览器应用和 Teams 中的任务创建的任务也会发生同样的情况。当 Planner 移动应用程序创建新任务时，不会发生这种情况。

更新以前分配的任务

该脚本还包括处理先前分配的任务更新的代码。这是通过将计划中未完成的任务集（使用 Get-MgPlannerPlanTask cmdlet 检索）与在 CSV 文件中的脚本运行之间存储的服务公告集进行比较来完成的。如果发现更新，脚本将使用 Update-MgPlannerTaskcmdlet 更新任务。如有必要，将使用 Update-MgPlannerTaskDetail cmdlet。

该脚本执行的最后一件事是将服务公告集导出到 CSV 文件，为下次运行做准备。事实上，与现有任务同步更新是我最不信任的代码，因为我没有花太多时间处理它。如果您有时间和兴趣，请认为检查和改进代码是一项挑战。

获取并运行脚本

图 3 显示了结果：在 Planner 计划中创建的一组任务分配给指定的负责人并带有适当的标签。简而言之，剧本有效（著名的遗言）。至少，对我来说是这样。

您可以从 GitHub 下载完整的脚本。要以交互方式运行脚本，使用 Connect-MgGraph 登录的帐户必须是拥有该计划的组的成员。这是因为 Graph SDK cmdlet 使用交互式会话的委派权限。另一方面，如果脚本使用应用程序和证书指纹进行身份验证以交互方式运行，或者使用托管标识作为计划的 Azure 自动化 Runbook 运行，则 cmdlet 可以使用应用程序权限并可以访问任何计划。

交互式会话使用Tasks.ReadWrite 权限。应用程序权限为Tasks.ReadWrite.All。这里的逻辑是，第一个是有权处理登录用户有权访问的计划中的任务。第二个允许后台进程访问所有计划（这是使用应用程序权限来分析 Planner 任务的示例）。请记住，如果使用 Azure 自动化 Runbook，自动化帐户的服务主体必须同意所有必需的权限。

创建和调试脚本的工作量比我预期的要多。部分原因是 Planner 开展业务的方式有些晦涩难懂。部分原因是缺乏文档。无论如何，追寻死胡同和有缺陷的想法的痛苦很快就会过去。通常需要注意的是，此代码旨在说明原理，而不是成熟的解决方案。即便如此，您仍可以享受通过 PowerShell 使用 Planner 的乐趣。