使用 Graph API 报告 Planner 数据

图形应用程序权限使报告计划变得更容易

三年前，我描述了使用 Graph API 报告有关 Planner 计划的信息时遇到的一些挫折。基本问题是缺乏 Planner Graph API 的应用程序权限。当时仅提供委派权限，这意味着您只能报告属于您所属的 Microsoft 365 组的计划的详细信息。由于缺乏权限，其他计划仍然无法访问。

应用程序权限允许 Azure AD 应用程序在没有登录用户的情况下访问数据。微软承诺使用应用程序权限更新 Planner Graph API，但明显缺乏进展让那些想要出于管理目的与计划进行交互的人感到失望。例如，微软没有用于 Planner 的备份 API，并且缺乏应用程序权限迫使人们向每个有计划的组添加一个管理员帐户来备份计划数据，或者将计划数据移动到另一个租户。

但最近（我不知道具体是什么时候，因为几个月前我就停止检查了），Planner Graph 的 Tasks.Read.All 和 Tasks.ReadWrite.All 应用程序权限API 出现了。

Microsoft Graph PowerShell SDK 仅限于委托的 Tasks.Read 和 Tasks.ReadWrite 权限，这意味着它的 cmdlet（例如 Get-MgGroupPlannerPlan ) 只能与登录帐户可以访问的计划进行交互。任何分配应用程序权限的尝试都会被拒绝，并出现奇怪的错误。一方面，我理解这一限制，因为 SDK 使用委托权限作为规范。但是，在计算会话中可用的有效权限集时，SDK 还会考虑 Azure AD 管理员角色。因此，允许将应用程序权限分配给 SDK，以便具有管理员权限的帐户可以使用它似乎是合理的。但这是不可能的（目前）。

使用 Azure AD 注册的应用程序访问 Planner 数据

解决方案是使用 Azure AD 注册的应用程序来访问其资源集中有计划的每个 Microsoft 365 组的 Planner 数据。为了测试原理，我创建了一个新的 Azure AD 注册应用程序，并授予管理员以下应用程序权限的同意：

• Directory.Read.All（读取目录信息）。
• Group.Read.All（读取组信息）。
• Tasks.Read.All（读取计划信息）。

然后我创建了一个应用程序密钥用于测试。在生产中，使用证书或使用具有托管标识的 Azure 自动化 Runbook 更安全（在这种情况下，必须为自动化帐户的服务主体分配必要的权限）。

使用 PowerShell 访问规划器数据

借助应用程序标识符、租户标识符和应用程序密钥，我们可以向 Azure AD 请求包含应用程序权限的访问令牌，并使用它来发出 Graph API 请求。这段代码没有什么神秘之处，因为这是一条老路。

脚本中的基本步骤是：

• 查找租户中的所有 Microsoft 365 组。
• 对于每个组，检查它是否有任何计划。最初，一个团队只能有一个计划，但微软取消了这一限制，允许 Teams 支持多个渠道的计划。
• 如果找到计划，请提取计划的详细信息。
• 报告数据。

为了检查组中的计划，我使用了以下代码（Get-GraphData 是一个辅助函数，用于运行 Invoke-RestRequest cmdlet 并处理结果）：

$Uri = ("https://graph.microsoft.com/v1.0/groups/{0}/planner/plans" -f $Group.Id)
[array]$Plans = Get-GraphData -Uri $Uri -AccessToken $Token

当一个组有一个计划时，返回的数据（对于单个计划）如下所示：

@odata.etag     : W/"JzEtUGxhbiAgQEBAQEBAQEBAQEBAQEBAVCc="
createdDateTime : 2020-06-09T14:45:19.2940321Z
owner           : 107fe4dd-809c-4ec9-a3a1-ab88c96e0a5e
title           : Plans
id              : N6TvImQH70KdUzZGk25B5JYAF77k
createdBy       : @{user=; application=}
container       : @{containerId=107fe4dd-809c-4ec9-a3a1-ab88c96e0a5e; type=group;
                  url=https://graph.microsoft.com/v1.0/groups/107fe4dd-809c-4ec9-a
                  3a1-ab88c96e0a5e}

该脚本检查容器（Planner 描述计划的方式）是否存在，然后继续获取每个计划的任务。这是一个调用的示例：

$Uri =  ("https://graph.microsoft.com/v1.0/planner/plans/{0}/tasks" -f $Plan.id)
[array]$Tasks = Get-GraphData -Uri $Uri -AccessToken $Token

获取任务后，脚本计算一些数据，例如：

• 计划中最新和最旧任务的时间戳。
• 每个优先级（紧急、重要、中等和低）的任务数量。 Planner 使用数值表示优先级，对应的值为 1、3、5 和 9。
• 每个进度阶段的任务数量（已完成、正在进行、未开始）。 Planner 将进度存储为百分比值 100、50 和 0。
• 用于组织计划中任务的存储桶（即使计划不包含任何任务，它也有一个默认存储桶）。对于每个存储桶，脚本计算活动任务和已完成任务的数量以及已完成任务的百分比。

要检索计划的存储桶，该脚本使用：

$Uri =  ("https://graph.microsoft.com/v1.0/planner/plans/{0}/buckets" -f $Plan.id)
[array]$Buckets = Get-GraphData -Uri $Uri -AccessToken $Token

为每个计划检索的信息将进入 PowerShell 列表以供以后处理。

各种 API（如列表计划）的 Microsoft 文档提供了一些额外的详细信息。

报告数据

处理链接到 Microsoft 365 组的所有计划后，脚本将处理数据以创建 HTML 报告。这里的目的不是生成世界上最好看的报告。相反，该脚本会生成一份报告，其中属于一个组的所有计划都列出在一起。对于找到某些任务的每个计划，该脚本包括对每个存储桶的分析，包括任务数量、已完成的任务、活动（未启动或正在进行）任务以及活动任务的百分比。这只是为计划提取的数据可以做什么的一个示例。

图 1 显示了我的租户的报告摘录，其中显示了 Office 365 for IT Pros 电子书团队用于组织 Microsoft 365 消息中心中发布的可能影响图书内容的潜在更改的计划的详细信息。该计划称为 MAC 任务，您可以看到桶分析在突出显示需要工作的区域方面有多么有用。

自己测试一下

该脚本可从 GitHub 下载。请记住，该代码并不是 Planner 报告的完美解决方案。它旨在实际演示 Planner Graph API 支持应用程序权限后的可能性。请随意在 GitHub 中提出更改建议（或进行更改）。

在运行脚本之前，需要在租户中创建 Azure AD 注册应用程序，并调整应用程序标识符、租户标识符和应用程序密钥的值。之后，浏览计划、任务和桶的内部应该会很顺利。

Active Directory 的网络安全风险管理

了解如何通过这些网络安全风险管理解决方案预防 AD 攻击并从中恢复。