Microsoft Graph PowerShell SDK 简介

Microsoft 365 管理的统一方法

Microsoft Graph API 已经存在一段时间了，微软正在将更多管理功能（例如 Azure AD 帐户的许可证管理）转移到该平台。当 Microsoft 将功能转移到 Graph 时，组织可能必须更新 PowerShell 脚本。

开始使用 Graph API 可能是一项艰巨的任务，特别是如果您没有基于 REST 的服务的经验。通过一些实践和花时间阅读 Graph 文档，可以了解 Microsoft 365 租户迁移评估等工具是如何组合在一起的，并开始了解使用 Graph 的价值。

如果您想要以更熟悉的方式利用 Graph，Microsoft Graph PowerShell SDK 可以简化该过程并将其打包到（相对）简单的 PowerShell 模块中。使用 PowerShell SDK 连接到 Microsoft Graph 存在一些问题，但它使租户管理员学习和采用 Graph API 的过程变得更加容易。

在有关使用 Microsoft Graph PowerShell SDK 的系列的第一部分中，我解释了 SDK 是什么以及开始时需要考虑的事项。

什么是 Microsoft Graph API？

查看 Microsoft Graph API（或任何 Graph API）的一种方法是将其视为逻辑树结构中的一组节点。该请求将发送到表示您要访问的数据的端点。

例如，用户端点 (https://graph.microsoft.com/v1.0) 返回租户中的所有用户，但为了获取特定用户（例如 [email protected]）的数据，我们查询端点https://graph.microsoft.com/v1.0/[email protected]。

此逻辑沿着如图 1 所示的结构继续。例如，端点 https://graph.microsoft.com/v1.0/[email protected]/Messages 返回以下电子邮件： [email protected]，而终结点 https://graph.microsoft.com/v1.0/[email protected]/ 返回详细信息一条单独的消息。

Microsoft Graph Explorer 是探索不同端点及其返回信息的有用方法。它还附带了一个用于查询的示例数据集，以便您可以在将其连接到生产租户之前熟悉该工具。在图 2 中，我们看到了用户 AdeleV 的 manager 端点的 Graph Explorer 结果。

图形查询的结果以 JSON 格式返回，该格式足够灵活，可以考虑不同类型的值和嵌套对象。

使用 Graph API 时要考虑的另一件事是您运行的每个端点和操作所需的权限。要了解有关 Microsoft Graph API 中的权限的更多信息，请查看有关如何确定您需要的 Microsoft Graph 权限的文章。

PowerShell SDK 有什么帮助？

对于许多租户管理员来说，使用 Graph API 是一个新概念，并且需要掌握一个学习曲线。 PowerShell SDK 为更熟悉 PowerShell 的管理员提供了一种使用图表的方法，而无需担心身份验证令牌和格式化请求等细节。

SDK 通过提供代表您发出图形调用的 PowerShell cmdlet 来实现此目的。例如，在图 3 中，我们看到 PowerShell SDK 中的 Get-MgGroup cmdlet 向端点发出 GET 请求 https://graph.microsoft.com/v1.0/groups 。虽然可以使用 Invoke-WebRequest 直接发送此请求，但拥有一组更熟悉的 cmdlet 和参数可以显着简化图形的使用。

通过 Graph 创建新对象或更新现有对象时，需要 JSON 负载来定义新对象或更新对象的参数。此有效负载遵循每种对象类型的预定义模式，但很难正确理解。 SDK cmdlet 根据 cmdlet 参数自动格式化有效负载。例如，在图 4 中，New-MgUser cmdlet 传递 Graph API 所需的 JSON 数据来创建新用户。

使用 Microsoft Graph PowerShell SDK Cmdlet 的 -Debug 参数是了解 SDK 在后台执行的操作并查看发送到 Graph API 的请求的好方法。

Active Directory 的网络安全风险管理

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

安装PowerShell SDK

Microsoft Graph PowerShell SDK 可在 PowerShell 库中获取。要安装 SDK，必须注册 PSGallery 存储库，如果没有它，安装将失败，如图 5 所示。要注册存储库（如果缺少），请运行 cmdlet Register-PSRepository -Default, 然后安装应该可以工作。

安装 SDK 后，即可使用 39 个新模块（在撰写本文时计数正确）。

更新 SDK 相对轻松，以管理员身份运行 cmdlet Update-Module Microsoft.Graph 并重新启动 PowerShell。 SDK 每月更新一次，使用最新版本非常重要。

使用 Azure 自动化

自动化是 PowerShell 的一个关键因素。任务自动化对于 Microsoft 365 租户的日常运行通常至关重要，因为它允许管理员专注于在其他地方增加价值。虽然 SDK 作为 Windows 服务器中的计划任务运行得非常好，但 Azure 自动化为自动化任务添加了额外级别的安全性和可用性。

本文有关将适用于 PowerShell 的 Microsoft Graph SDK 与 Azure 自动化结合使用的文章介绍了在 Azure 自动化中运行 Graph SDK 的要求。

委派与应用程序权限

Microsoft Graph 支持两种类型的权限：委托 和应用程序。在较高级别上，委派权限的运行就像用户存在一样，并且通常要求用户以交互方式进行身份验证和检索访问令牌。委派权限通常用于代表最终用户连接到图表的客户端应用程序，并且是 PowerShell SDK 和 Graph Explorer 的默认方法。使用委派权限的应用程序仅限于登录用户可用的权限，因此使用 SDK 的非管理员用户只能执行其帐户有权执行的任务。

应用程序权限作为应用程序注册运行并支持非交互式身份验证。应用程序权限通常用于自动化任务或无法使用交互式身份验证的应用程序。为 Graph SDK 配置应用程序权限需要使用 Azure AD 中注册的应用程序。由于应用程序权限不以当前用户身份运行，因此它们不受委派权限的权限限制。使用应用程序权限时要小心，特别是在存储客户端机密或证书时。

在委派权限和应用程序权限之间进行选择时的另一个考虑因素是功能。 Microsoft 365 中的某些任务必须由用户完成。例如，这篇关于使用 Microsoft PowerShell Graph SDK 创建新的 Microsoft 365 组的文章介绍了如何设置 Microsoft 365 组并分配敏感度标签，这在使用委派权限时效果很好。尝试对应用程序权限执行相同操作会失败，因为仅应用程序令牌不支持此操作（图 6）。

有许多类似的细微差别会影响所需权限的类型。在规划代码时，检查文档以确定可能在哪里发现问题非常重要。

使用 SDK 连接到图表

使用 SDK 连接到 Graph API 的方法有多种，具体取决于您想要如何使用 cmdlet。最常见的连接场景是：

• 通过委派权限进行交互连接
• 使用应用程序权限和证书以非交互方式连接
• 使用应用程序权限和客户端密钥以非交互方式连接
• 使用 Azure 自动化和托管标识进行连接

使用委派权限进行连接很可能是人们尝试的第一种方法，也是最容易做到的方法。运行 cmdlet Connect-MgGraph 并指定您希望提示登录并同意授予 PowerShell 应用的范围，如图 7 所示。

通过脚本使用图形应用程序权限需要已注册的 Azure AD 应用程序并同意使用必要的权限。我不会在这里详细介绍如何创建应用程序注册，因为它已经讨论过很多次了（例如这篇有关使用 Graph API 预填充 Outlook 联系人的文章），但在应用程序注册到位后，Connect-MgGraph cmdlet 接受客户端证书 或访问令牌 参数。

使用客户端证书（如有关使用 Microsoft Graph PowerShell SDK 中基于证书的身份验证的文章中所示）是使用 PowerShell SDK 安全地自动执行任务的好方法（只要您确保存储证书）位于安全位置，例如 Azure Key Vault）。

要使用客户端密钥，您首先需要获取访问令牌。获取 Graph API 的访问令牌的方法有多种，但一种简单的方法是使用 Microsoft 身份验证库 PowerShell 模块 (MSAL.PS)，如使用 Azure 自动化通过 PowerShell 处理 Exchange Online 数据一文中所述。

图 8 显示了两种方法的实际效果。

将适用于 PowerShell 的 Microsoft Graph SDK 与 Azure 自动化结合使用是自动执行长时间运行或复杂脚本的好方法。 Microsoft Graph SDK 还可以通过 Azure 自动化使用托管标识，向托管标识的服务主体分配权限，并使它们直接可供自动化帐户使用。

概括

在本文中，我将介绍 Microsoft Graph PowerShell SDK 如何通过 Microsoft Graph API 简化 Microsoft 365 的管理。我还展示了如何在各种场景中使用 SDK 连接到图表。在使用图表时建立联系并理解要求是许多管理员在尝试更新代码时遇到的第一个重大挑战。

在本系列的第二部分中，我们将深入探讨如何通过 SDK 使用 Microsoft Graph，并查看一些示例，了解它可以通过自动化和批量处理节省您的时间和精力。