MSGraphMailbag - 对 Microsoft Graph PowerShell SDK 的深入研究

Posted 2021-06-26 Justin-Liu

本篇主要介绍 Microsoft Graph PowerShell SDK。

导引

Microsoft Graph API 非常庞大，有数千个端点。因此，PowerShell SDK 包含了成千上万的 cmdlet (或 commandlet)，它们分别分布在几十个模块中。因此，很难确定执行特定查询所需的正确的 cmdlet。

我们可以使用 PowerShell Get-Command cmdlet 来搜索 PowerShell SDK，以获得可用命令的列表。此外，我们可以搜索特定的词来帮助缩小搜索范围。例如，我们可能希望查找特定用户的所有日历事件。我们可以从 PowerShell SDK 中搜索所有包含 “calendar” 的命令：

Get-Command -Module Microsoft.Graph* *calendar*

这将我们需要查看的命令数量从数千个限制到更易于管理的数量，从而更容易找到适用的 cmdlet。

对于那些不熟悉 PowerShell cmdlet 的人，它使用“动词-[可选前缀]名词”的格式。Microsoft Graph PowerShell API 也遵循了这种命名约定，将 http 请求方法映射到 PowerShell 命令的谓词部分。GET 方法映射到一个“GET” PowerShell 命令。POST 和 PUT 方法映射到“新建”或“添加” PowerShell命令。PATCH 方法映射到“更新”或“设置”命令。DELETE 方法映射到一个“Remove”命令。

我们可以使用 Get-Command，通过动词和/或名词进一步过滤结果。通配符可以使用星号(*)。

Get-Command -Module Microsoft.Graph -Verb "Get"
Get-Command -Module Microsoft.Graph -Noun "Drive*"

找到正确的命令后，可以使用 PowerShell Get-Help cmdlet 查看执行所需请求可用的参数。

Get-Help Get-MgUserCalendarEvent -Detailed

在 Microsoft Graph API 文档和 Graph Explorer 或 Postman 这样的工具的帮助下，我们可以使用这些信息来确定脚本中使用的正确命令和语法。

现在我们有一定程度的熟悉了，接下来让我们看看如何使用 SDK 来实现 Microsoft Graph 中可用的一些核心功能。

查询参数

Microsoft Graph API 的一个强大功能是能够使用 OData 系统查询参数来控制返回的数据。在 RESTful 请求中，这些是作为提交的 URI 的一部分构建的。PowerShell SDK 通过命令参数 (如-Filter或-Search) 使这些查询选项可用。例如，如果我们想根据电子邮件消息 ID 返回一条消息，我们可以使用-Filter参数运行以下命令 (类似于 $filter 查询参数)：

Get-MgUserMessage -UserId [e-mail] -Filter "InternetMessageId eq '<[e-mail]>'"

我们不再返回邮箱中的所有消息，而是只返回与筛选器匹配的消息 (在本例中是特定的消息)。将我们的请求限定在特定需求范围内，同时使其更有效。

分页

对于提交过 Microsoft Graph API 请求的人来说，您可能对分页很熟悉。有些查询返回大量信息，因此使用多个页面返回数据。或者，您可能使用了$top 查询参数来指定返回的结果数量，从而导致对结果进行手动分页。无论采用哪种方法，想要从查询中获得所有数据，都需要确保处理所有返回的页面。

通常，我们会寻找响应中的 @odata.nextlink属性，并按照包含的 URL 查看结果的下一页。如果要构建 RESTful 查询，则需要将该逻辑构建到脚本中。

然而，使用 PowerShell SDK，分页处理起来要简单得多。就像 RESTful 请求一样，我们可以使用-Top 参数指定$top 查询。我们可以使用-Top 和-Skip 参数来为手动分页结果构建逻辑。此外，还有一个-PageSize 参数，用于控制每个页面返回的结果数量。

此外，-All 参数允许使用 PowerShell SDK 进行的查询自动处理分页并返回查询的所有结果，而不需要围绕@odata.nextlink 属性构建逻辑。它创建一个更简单的脚本体验。

限制 (Throttling)

像大多数基于云的服务有保护措施一样，Microsoft Graph 也不例外。节流通过限制在特定时间/并发/等维度上执行的请求数量来保护服务。

Microsoft Graph 文档说明了服务特定限制，以及处理限制的最佳实践。当限制发生时，Microsoft Graph 在响应中发送 HTTP 状态码 429 (太多请求)。许多服务 api 还提供了 Retry-After 响应头，它提供了用于延迟请求的等待时间。幸运的是，Microsoft Graph PowerShell SDK 为我们实现了重试逻辑。它将自动处理 429 状态码响应以及 Retry-After 响应头，免去了我们手动处理这些响应和调整请求的需要。

手动请求

尽管已经覆盖了 Microsoft Graph PowerShell SDK，但在某些情况下，我们可能需要发送一个特定的 Microsoft Graph 请求，而该请求并没有被 SDK 覆盖。在这种情况下，我们仍然能够使用 SDK 执行 RESTful web 请求。Invoke-MgGraphRequest cmdlet (类似于Invoke-RestMethod 命令) 为我们提供了指定 URI、方法、Headers 和 Body 来提交请求的能力。由于它是一个 SDK cmdlet，我们可以利用身份验证、访问令牌管理等。

该功能可能有用的一个例子是执行批处理请求。目前，SDK 中没有批处理命令，但是通过 Invoke-MgGraphRequest，我们可以利用该功能。构建一个 HTTP 请求并通过 Invoke-MgGraphRequest 提交它，我们能够执行一个批处理请求：

Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/$batch" -Body $body | ConvertTo-Json)

在本例中，我们为批处理过程提交一个 POST 请求，并将 JSON 格式的批处理命令传递给请求体。这相当于为我们提供了通过 PowerShell SDK 来使用 Microsoft Graph API 批处理功能。

总结

在这篇文章中，我们进一步了解了 Microsoft Graph PowerShell SDK，包括查找正确的 cmdlet、使用查询参数、分页结果、处理限制和发出手动请求。这样，我们就可以开始在脚本和应用程序中使用 Microsoft Graph PowerShell SDK 了。