使用 PowerShell 自动创建 Microsoft Planner 计划

自动从模板创建计划

最近一篇有关如何使用 Graph API 在 Microsoft 365 租户中报告计划的文章描述了为 Planner Graph API 添加应用程序权限支持如何帮助管理员自动与 Planner 计划进行交互。当使用 Microsoft Graph API 自动化流程时，应用程序权限特别有用，允许任务在没有用户身份验证提示的情况下运行。

基于这个想法，还可以自动创建计划，类似于如何自动化团队创建以保持团队环境整洁和安全。有许多示例说明可重复流程如何从使用 Planner 中受益，以确保跨复杂流程或项目跟踪任务。我在本文中使用的一个相关示例是在规划 Microsoft 365 租户到租户迁移时。每次迁移的许多任务都是相同的，至少在规划阶段是这样。

在本文中，我将解释如何从可重复流程的模板创建 Planner 计划，以及如何自动配置以最大限度地减少管理工作。

注意：本文中使用的代码示例和模板文件可在 GitHub 上找到此处。

构建模板

在 GitHub 中，您可以找到一个非常基本的计划模板 CSV 文件，其中包含租户到租户迁移的一些常见任务和类别。 CSV 包含任务、存储桶和任务详细信息的列，这些列在配置计划时使用（图 1）。

创建注册应用程序并分配权限

与任何 Graph API 自动化脚本一样，需要 Azure AD 注册应用程序并获得所需应用程序权限的同意。令人惊讶的是，为计划配置应用程序权限只需要一项权限：

• Tasks.ReadWrite.All

此外，如果您计划包含“TeamsChannelName”参数以将 Planner 选项卡添加到团队，则需要以下附加权限：

• 团队选项卡.创建
• ChannelSettings.Read.All

创建注册的应用程序后，生成客户端密钥（用于测试），并记下生成访问令牌所需的客户端和租户 ID。对于在生产中运行脚本，我建议使用证书而不是客户端密钥进行身份验证，如使用 Azure 自动化通过 PowerShell 处理 Exchange Online 数据中所述。

Microsoft 平台迁移规划和整合

最大限度地降低与下一次 Exchange Online 域转移相关的风险、时间、成本和复杂性

设置环境

该脚本使用 Microsoft Graph PowerShell SDK 中的 Microsoft.Graph.Authentication 和 Microsoft.Graph.Planner 模块。您可以在本地工作站上安装这些模块（使用 cmdlet Install-Module Microsoft.Graph）或将它们与 Azure 自动化 Runbook 一起使用。如果使用 Azure 自动化，请确保 PowerShell 模块保持最新。

如果您计划包含“TeamsChannelName”参数以将 Planner 选项卡添加到团队，则还需要 Microsoft.Graph.Teams 模块。

此外，如果脚本在 Azure 自动化中运行，它会连接到 Azure Blob 存储以导入计划模板文件。这需要一个带有 blob 容器的存储帐户。在图 2 中，我创建了一个 blob 容器并上传了 PlanTemplate.csv。

为了连接到 Azure Blob 存储，该脚本利用 AZ PowerShell 模块。 Azure 自动化默认安装此模块，因此无需执行任何操作即可使该模块可供 Runbook 使用。您必须将读取 Blob（存储 Blob 数据读取器）的权限分配给自动化帐户的托管标识，如图 3 所示。托管标识是分配给自动化帐户的服务主体，如本文中有关使用 Exchange 的讨论具有 Azure 自动化托管标识的在线 PowerShell。

使用 PowerShell 创建计划

该脚本使用模板文件和下面列出的参数将计划添加到现有 Microsoft 365 组，并使用定义的存储桶和任务填充该计划。配置了以下参数：

• ClientID - ClientID 是必需参数，是 Azure AD 注册应用程序的客户端 ID。
• TenantID - TenantID 是必需参数，是 Azure AD 注册应用程序的租户 ID。
• ClientSecret - ClientSecret 是必需参数，是在 Azure AD 注册的应用程序中生成的客户端密钥。
• CSVFilePath - CSVFilePath 是必需参数，是 CSV 模板文件的相对路径。如果文件位于当前目录中，则仅指定 CSV 文件名。
• PlanName - PlanName 是必需参数，是新 Planner 计划的名称。
• GroupID - GroupID 是必需参数，并且是计划应添加到的 Microsoft 365 组的对象 ID。
• StorageAccountName - StorageAccountName 是可选参数，仅在 Azure 自动化中运行脚本时才需要。它是 Blob 容器所在的存储帐户的名称。
• StorageContainerName - StorageContainerName 是可选参数，仅在从 Azure 自动化运行时才需要。它是存储模板文件的 blob 容器的名称。
• TeamsChannelName - TeamsChannelName 是可选参数，是团队中要添加 Planner 选项卡的通道的显示名称。仅当您选择的 Microsoft 365 组具有关联的团队时，这才有效。

该脚本有五个主要部分：

• 导入 CSV 模板并请求 Microsoft Graph 访问令牌。
• 提供计划。
• 配置所有存储桶。
• 配置每个任务并添加任务详细信息。
• （可选）向计划的 Teams 频道添加选项卡

如果从 Azure 自动化运行，要从 Blob 存储导入模板，我们需要使用自动化帐户的托管标识连接到 Azure，并使用 Get-AzStorageBlobContent 下载 CSV 进行导入。

Connect-AZAccount -Identity

$context = New-AzStorageContext -StorageAccountName $storageaccountname

Get-AzStorageBlobContent -Blob $CSVFilePath -Container $StorageContainerName -Context $context

$csv = import-csv plantemplate.csv

为了创建计划，我们使用名称和目标组构建计划参数，然后运行 New-MgPlannerPlan cmdlet。

$params = @{
 container = @{
 url = "https://graph.microsoft.com/v1.0/groups/$groupid"
 }
 title = $planName
}
try {
 $plan = New-MgPlannerPlan -BodyParameter $params
}
catch {
 write-error "Could not create the plan. Error:`n $_"
 exit
}

接下来，通过识别 CSV 中唯一的存储桶名称集并使用 New-MgPlannerBucket cmdlet 创建每个存储桶来创建存储桶。使用 order 提示参数，存储桶按照模板中列出的顺序显示。如Planner文档所示，订单提示“！”为列表中的第一项指定。之后，通过指定前一个订单提示并后跟“！”，将其他项目添加到列表的末尾。

[array]$Buckets = ($csv | Select-Object Bucket -Unique)
$orderhint = " !"
$BucketList = @()
$i = 0
foreach ($bucket in $Buckets) {
 $i++
 Write-Progress -Activity "Creating Buckets" -Status "Creating Bucket $i of $($Buckets.count)" -PercentComplete (($i / $Buckets.count) * 100)
 $params = @{
 name = "$($bucket.Bucket)"
 planId = "$($plan.id)"
 orderHint = "$($orderhint)"
 }

$CreatedBucket = New-MgPlannerBucket -BodyParameter $params
 $BucketList += $CreatedBucket
 $orderhint = " $($createdBucket.orderhint)!"
}

接下来，脚本循环遍历模板中的任务集，以创建任务对象并分别使用 New-MgPlannerTask 和 Update-MgPlannerTaskDetail 参数添加任务详细信息。

$i = 0
foreach ($Task in $csv) {
 $i++
 Write-Progress -Activity "Creating Tasks" -Status "Creating Task $i of $($csv.count)" -PercentComplete (($i / $csv.count) * 100)
 $CurrentBucket = $BucketList | Where-Object { $_.name -eq $Task.Bucket }
 try {

 $params = @{
 planId = "$($Plan.id)"
 bucketId = "$($CurrentBucket.id)"
 title = "$($Task.task)"
 }

 $CreatedTask = New-MgPlannerTask -BodyParameter $params
 }
 catch {
 write-error "Could not create task: $($task.task), Error:`n $_"
 exit
 }

 $params = @{
 description = "$($Task.details)"
 previewType = "description"
 }
 ##Update Plan Details
 try {

 Update-MgPlannerTaskDetail -PlannerTaskId $CreatedTask.Id -BodyParameter $params -IfMatch (Get-MgPlannerTaskDetail -PlannerTaskId $CreatedTask.id).AdditionalProperties["@odata.etag"]
 }
 catch {
 write-error "Could not update task details: $($task.task), Error:`n $_"
 exit
 }
}

最后，如果指定了 TeamsChannelName 参数，则使用 New-MgTeamChannelTab 参数将新计划作为选项卡添加到 Microsoft 365 组的团队中。

if ($TeamsChannelName) {
 Try {
 $ChannelID = (Get-MgTeamChannel -TeamId $groupid | ?{$_.DisplayName -eq $TeamsChannelName}).id
 $params = @{
 name = $PlanName
 displayName = $PlanName
 "teamsapp@odata.bind" = "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/com.microsoft.teamspace.tab.planner"
 configuration = @{
 contentUrl = "https://tasks.teams.microsoft.com/teamsui/{tid}/Home/PlannerFrame?page=7&auth_pvr=OrgId&auth_upn={userPrincipalName}&groupId={groupId}&planId=$($plan.id)&channelId={channelId}&entityId={entityId}&tid={tid}&userObjectId={userObjectId}&subEntityId={subEntityId}&sessionId={sessionId}&theme={theme}&mkt={locale}&ringId={ringId}&PlannerRouteHint={tid}"
 removeUrl = "https://tasks.teams.microsoft.com/teamsui/{tid}/Home/PlannerFrame?page=13&auth_pvr=OrgId&auth_upn={userPrincipalName}&groupId={groupId}&planId=$($plan.id)&channelId={channelId}&entityId={entityId}&tid={tid}&userObjectId={userObjectId}&subEntityId={subEntityId}&sessionId={sessionId}&theme={theme}&mkt={locale}&ringId={ringId}&PlannerRouteHint={tid}"
 websiteUrl = "https://tasks.office.com/{tid}/Home/PlanViews/$($Plan.id)?Type=PlanLink&Channel=TeamsTab"
 }
 }
 $CreatedTab = New-MgTeamChannelTab -TeamId $groupid -ChannelId $ChannelID -BodyParameter $params
 }
 catch {
 write-error "Could not create tab for task: $($task.task), Error:`n $_"
 exit
 }

执行计划

脚本运行后，目标 Microsoft 365 组的成员将从 Planner 应用中看到新的 Planner 计划，并且所有任务都将配置在正确的存储桶中（图 4）。

如果使用 TeamsChannelName 参数，该选项卡也可在团队中使用，如图 5 所示。脚本使用默认的“Tasks by Planner”Teams 应用程序，这会向选项卡添加完整功能。

通过模板创建计划，从事租户到租户迁移的团队可以开始使用该计划，而无需为每个项目从头开始创建新计划。当同一基本计划多次使用时，这尤其有用。我在这里展示的示例相对基本，但是可以添加更多内容来满足您自己的要求。例如，我只为每个任务添加了标准描述，但 Planner 还支持清单和附件，可用于为输出提供更多深度。一旦配置了基础知识（例如存储帐户和应用程序注册），就可以相对轻松地对计划的配置方式进行任何其他调整。