避免 PowerShell 脚本中常见的图形 API 错误

使用图形 API 时掌握正确的基础知识

鉴于我撰写的有关基于 Microsoft Graph API 或 Microsoft Graph PowerShell SDK 开发 PowerShell 脚本的文章数量，在从我的 GitHub 存储库下载脚本并尝试运行后，我不可避免地会收到遇到 Graph API 错误的人们的许多问题。他们的租户中的代码。在本文中，我描述了向我报告的一些常见问题以及潜在的解决方案。

它是 PowerShell，所以它是您的代码

PowerShell 的一大优点是，一旦您下载了脚本的副本，它就成为您的代码。代码中没有隐藏秘密，您可以完全控制更改代码以满足您的要求。巨大的责任伴随着巨大的权力，这意味着您负责维护租户的代码。其他人无法访问您的 Microsoft 365 数据。其他人都无法修改分配给 PowerShell 脚本使用的应用程序的图形权限。

因此，支持是您的责任。只有你可以调整租户设置或更新 Azure AD 以解决运行脚本时遇到的问题。将您下载的每个脚本视为潜在危险，直到您完成对其代码的完整端到端审查并准确了解该代码的用途。除此之外，这将识别脚本访问的数据以及图形应用程序权限和 Azure AD 管理角色所需的权限。

正确配置的应用程序是避免图形 API 错误的关键

PowerShell 脚本可以通过两种方式运行 Graph API 请求：

1. 使用 Microsoft Graph PowerShell SDK 中的 cmdlet。
2. 通过 Invoke-RestMethod cmdlet 传递 URL 以运行图形请求。

在这两种情况下，图形都会通过 Azure AD 中注册的应用程序与脚本进行通信。该应用程序可以是企业应用程序，这意味着它由 Microsoft 或另一方（如 Adobe）创建和维护，并且旨在供多个租户使用，也可以是特定于您的租户的应用程序。两者都是具有服务主体的 Azure AD 客户端应用程序。我们很快就会联系服务主体。

对于许多 PowerShell 脚本来说，与 Graph 进行通信的第一步是向 Azure AD 注册新的客户端应用程序。该过程很简单，会生成通过 Azure 进行身份验证并保护访问令牌所需的三条信息中的两条。这些项目是：

• 客户端（或应用程序）标识符。
• 租户（或目录）标识符。

图 1 显示了已注册客户端应用程序的详细信息，您可以看到客户端标识符和租户标识符。身份验证所需的最后一条信息是证明应用程序身份的某种方法，或者是应用程序已知且 Azure AD 已知的信息。

出于测试目的，脚本通常使用应用程序机密作为身份证明。在生产中使用应用程序机密不是一个好主意（如果将应用程序机密存储在安全的地方（例如 Azure Key Vault），则可能是一个例外）。生产脚本更经常使用基于证书的身份验证，其中应用程序将证书或指纹传递到 Azure AD 以证明其身份。

有了这三条信息，应用程序就可以请求 Azure AD 颁发访问令牌，代码如下：

# Construct URI and body needed for authentication
$uri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
$body = @{
    client_id     = $AppId
    scope         = "https://graph.microsoft.com/.default"
    client_secret = $AppSecret
    grant_type    = "client_credentials"
}
# Get OAuth 2.0 Token
$TokenRequest = Invoke-WebRequest -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Body $body -UseBasicParsing
# Unpack Access Token
$Token = ($tokenRequest.Content | ConvertFrom-Json).access_token

Azure AD 访问令牌包含应用程序可以使用的权限的详细信息。保护访问令牌是 PowerShell 脚本成功使用 Graph API 的第一步。访问令牌的有效期约为 59 分钟，之后必须更新才能继续有效。

这不是我，而是应用程序！

图形权限由应用程序持有，不会分配给用于登录 PowerShell 的用户帐户。这与传统的 PowerShell 模块不同，在传统的 PowerShell 模块中，用户帐户所拥有的管理角色决定了 cmdlet 可以执行的操作。

例如，您的帐户可能拥有 Exchange Online 管理员角色，但这并不意味着您可以运行邮箱内容报告脚本来检索有关用户邮箱中内容的信息。当 Graph 评估应用程序是否可以执行获取数据的请求时，它会根据分配给应用程序的权限而不是其他任何内容来执行此操作。

图权限的另一个关键方面是委派权限和应用程序权限之间的区别。简而言之，委派权限允许应用程序访问属于登录帐户的数据。应用程序权限允许应用程序访问整个租户的数据，这就是应用程序必须获得管理员同意才能使用应用程序权限的原因。在大多数情况下，PowerShell 脚本用来执行管理操作的应用程序需要应用程序权限。

图 2 显示了分配了多个图形应用程序权限的应用程序。在大多数情况下，脚本不需要如此严格权限的应用程序。

当人们尝试运行示例脚本时，我遇到的大多数问题都是由于应用程序缺少重要权限或使用委派权限而不是应用程序权限造成的。

服务负责人

每个应用程序都有一个服务主体。考虑服务主体的一种方法是，它是 Azure AD 存储应用程序权限和角色的一种便捷方式。当您在交互式会话中从 Microsoft Graph PowerShell SDK 运行 cmdlet 时，权限来自 Graph PowerShell 应用的服务主体。这是 Microsoft 维护的企业应用程序的示例。应用程序的服务主体拥有交互式会话中 SDK cmdlet 可用的权限。虽然方便，但这种安排的缺点是服务主体可能会获得高度许可。

为了说明这一点，请运行 Get-MgContext cmdlet 来报告 SDK 服务主体所拥有的可用范围（权限）：

(Get-MgContext).Scopes
Analytics.Read
Application.Read.All
Application.ReadWrite.All
AppRoleAssignment.ReadWrite.All
AuditLog.Read.All
Channel.ReadBasic.All
ChannelMessage.Read.All
ChannelMessage.Send
ChannelSettings.Read.All
Contacts.ReadWrite
DelegatedPermissionGrant.ReadWrite.All
Directory.AccessAsUser.All
Directory.Read.All
Directory.ReadWrite.All
email
Group.Read.All
Group.ReadWrite.All
GroupMember.Read.All
GroupMember.ReadWrite.All
IdentityProvider.ReadWrite.All
Mail.Read
Mail.ReadWrite
Mail.Send

当您在非交互模式下运行 SDK cmdlet 时，您将使用具有自己的一组权限的已注册客户端应用程序。应用程序可以使用基于证书的身份验证，或者脚本可以使用托管标识在 Azure 自动化中运行，并使用自动化帐户的服务主体来保存其权限。

可怕的 403 错误

如果 Graph 请求产生 403 错误，则意味着应用程序无权发出该请求。换句话说，它没有必要的应用程序权限，并且 Graph 恭敬地拒绝允许访问。如果您看到 403 错误，请检查分配的权限并确保管理员同意应用程序使用这些权限。

在大多数情况下，脚本包含注释来告诉管理员需要哪些权限。如有必要，您可以检查不同的来源以了解发出图形请求需要哪些权限。

Microsoft 的 Graph API 文档始终列出所需的权限。例如，图 3 显示，如果应用具有多个权限之一（包括 Group.Read,All），则可以运行 Graph List Groups API。

Microsoft 的 Graph API 文档最近稳步改进，其中包含可以插入 Graph Explorer 来测试请求的示例。许多 API 现在都包含使用 SDK cmdlet 的 PowerShell 示例。 PowerShell 示例往往非常基础，但足以入门。例如，要获取组列表，List Groups API 文档建议：

Get-MgGroup

该命令有效，但仅获取租户中的前 100 个组。获取所有组的更好示例是：

Get-MgGroup -All

未获得所有预期数据

为了限制资源的潜在压力，图形 API 在包含项目集的页面中返回数据。通常，一个页面包含 100 个项目，对图形 API 的调用将返回这些项目，而不会返回更多项目，即使有更多匹配的项目可用。这种机制称为分页，开发人员有责任检查是否有更多数据可用并继续获取，直到检索到所有数据。

图形请求使用 Top 查询参数一次获取特定数量的项目。然而，Top 参数通常限制为 999 个项目。更好的解决方案是让脚本检查 Graph 请求返回的信息是否包含 nextlink。下一个链接是指向要获取的下一页数据的 URL，其想法是继续获取数据，直到图表不返回下一个链接。通常，脚本包含处理分页的函数（例如，请参阅团队和组活动报告脚本中的 Get-GraphData 函数）。

某些 SDK cmdlet 通过支持 All 参数来强制检索所有匹配数据来处理分页。这些 cmdlet 包括 Get-MgUser、Get-MgGroup 和 Get-MgTeam（仅限测试版）。如果有疑问，请检查文档！

混淆

Microsoft 365 生成大量有关用户活动的数据，这些数据显示在 Microsoft 365、SharePoint Online 和 Teams 管理中心的报告部分中。应用程序通过图形报告 API 检索使用情况数据。为了保护用户隐私，Microsoft 365 实施了一项设置，通过在图表检索使用数据时隐藏显示名称和类似信息来混淆信息（图 4）。该设置位于 Microsoft 365 管理中心“设置”部分的“报告”下。

如果组织选择混淆使用数据，则这些设置会影响所有管理中心以及使用图形报告 API 检索信息的任何其他应用程序。要查看真实数据，您可以在运行报告之前以编程方式更改设置并在运行后恢复。 例如，用户活动报告脚本（用于检索过去 180 天内跨 Exchange Online、Teams、SharePoint Online、OneDrive for Business 和 Yammer 的用户活动统计信息）无法使用模糊数据，因为无法整理数据来自多个工作负载，因此这是在脚本运行之前必须删除混淆的一个很好的例子。

通过掌握正确的基础知识来避免图形 API 错误

如果您掌握了正确的基础知识，那么在 PowerShell 中使用图形 API 并不困难。正确配置应用程序并分配和同意必要的权限应该可以解决大多数潜在问题。之后，代码就是PowerShell，您可以根据需要修复、调整、改编和改进它。

最后，如果脚本使用 Microsoft Graph PowerShell SDK，请确保安装并使用该模块的最新版本。 Microsoft 定期更新 SDK 以修复问题并引入新的 cmdlet。如果工作站运行了过时的模块而出现问题，那将是一件很遗憾的事情。

Microsoft 平台迁移规划和整合

简化迁移规划，克服迁移挑战，更快地完成项目，同时最大限度地降低成本、风险和对用户的干扰。