使用 Microsoft Graph 生成 PowerShell 脚本 - Microsoft Graph

本教程介绍如何生成使用 Microsoft 图形 API代表用户访问数据的 PowerShell 脚本。

注意

若要了解如何使用 Microsoft Graph 通过仅限应用的身份验证访问数据，请参阅此仅限应用的身份验证教程。

在本教程中，你将：

提示

作为本教程的替代方法，可以通过快速启动工具下载完成的代码，该工具可自动执行应用注册和配置。下载的代码无需进行任何修改即可正常工作。

还可以下载或克隆 GitHub 存储库，并按照 README 中的说明注册应用程序并配置项目。

先决条件

在开始本教程之前，应在开发计算机上安装 PowerShell 。 PowerShell 5.1 是最低要求，但建议使用 PowerShell 7。

你还应具有具有Exchange Online邮箱的 Microsoft 工作或学校帐户。如果没有 Microsoft 365 租户，可以通过 Microsoft 365 开发人员计划获得一个租户;有关详细信息，请参阅常见问题解答。或者，可以注册 1 个月的免费试用版或购买 Microsoft 365 计划。

注意

本教程使用 PowerShell 7.2.2 和 Microsoft Graph PowerShell SDK 版本 1.9.5 编写。本指南中的步骤可能适用于其他版本，但尚未测试。

在门户中注册该应用

剩余 20 分钟

在本练习中，你将在 Azure Active Directory 中注册一个新应用程序以启用用户身份验证。可以使用 Azure Active Directory 管理中心或使用 Microsoft Graph PowerShell SDK 注册应用程序。

注册应用程序进行用户身份验证

在本部分中，你将注册一个支持使用设备代码流进行用户身份验证的应用程序。

注意

为 Microsoft Graph PowerShell SDK 注册应用程序进行用户身份验证是可选的。 SDK 具有自己的应用程序注册和相应的客户端 ID。但是，使用自己的应用程序 ID 可以更好地控制特定 PowerShell 脚本的权限范围。

Azure AD 管理中心
PowerShell

打开浏览器，导航到 Azure Active Directory 管理中心，并使用 工作或学校帐户登录。
选择左侧导航栏中的“Azure Active Directory”，再选择“管理”下的“应用注册”。
选择“新注册”。输入应用程序的名称，例如 Graph User Auth Tutorial。

根据需要设置 支持的帐户类型 。选项包括：

选项	谁可以登录？
仅限此组织目录中的帐户	仅 Microsoft 365 组织中的用户
任何组织目录中的帐户	任何 Microsoft 365 组织中的用户 (工作或学校帐户)
任何组织目录中的帐户...和个人 Microsoft 帐户	任何 Microsoft 365 组织中的用户 (工作或学校帐户) 和个人 Microsoft 帐户

保留“重定向 URI”为空。
选择“注册”。在应用程序的 “概述 ”页上，复制 “应用程序 (客户端) ID ”的值并保存它，下一步将需要它。如果 为此组织目录中的“帐户”选择“仅 支持 帐户类型”，则还要复制 “目录 (租户) ID 并保存它。
选择“管理”下的“身份验证”。找到 “高级设置” 部分，将 “允许公共客户端流” 切换开关更改为 “是”，然后选择“ 保存”。

若要使用 PowerShell，需要 Microsoft Graph PowerShell SDK。如果没有，请参阅安装 Microsoft Graph PowerShell SDK 了解安装说明。

重要

PowerShell 脚本需要具有应用程序管理员、云应用程序管理员或全局管理员角色的工作/学校帐户。如果帐户具有应用程序开发人员角色，则可以在 Azure AD 管理中心注册。

创建名为 RegisterAppForUserAuth.ps1 的新文件，并添加以下代码。

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

保存文件。
打开 PowerShell，将当前目录更改为 RegisterAppForUserAuth.ps1的位置。

运行以下命令，将 <受众值> 替换为所需的值 (请参阅下表) 。

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth Tutorial" -SignInAudience <audience-value>

SignInAudience 值	谁可以登录？
`AzureADMyOrg`	仅 Microsoft 365 组织中的用户
`AzureADMultipleOrgs`	任何 Microsoft 365 组织中的用户 (工作或学校帐户)
`AzureADandPersonalMicrosoftAccount`	任何 Microsoft 365 组织中的用户 (工作或学校帐户) 和个人 Microsoft 帐户
`PersonalMicrosoftAccount`	仅个人 Microsoft 帐户

按照提示在浏览器中打开 https://microsoft.com/devicelogin ，输入提供的代码，然后完成身份验证过程。
复制脚本输出中的 客户端 ID 和 身份验证租户 值。在下一步中，你将需要这些值。
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

注意

请注意，你未对应用注册配置任何 Microsoft Graph 权限。这是因为此示例使用动态同意请求用户身份验证的特定权限。

添加用户身份验证

剩余 17 分钟

在本部分中，你将作为 Microsoft Graph 的用户对 PowerShell 会话进行身份验证。这是获取调用 Microsoft Graph 所需的 OAuth 访问令牌所必需的。

Microsoft Graph PowerShell SDK 提供两种用于用户身份验证的身份验证方法：交互式浏览器和设备代码身份验证。交互式浏览器身份验证使用设备的默认浏览器允许用户登录。设备代码身份验证允许在没有默认浏览器的环境中进行身份验证。在本练习中，你将使用设备代码身份验证。

重要

如果尚未安装 Microsoft Graph PowerShell SDK，请立即安装它，然后再继续操作。

对用户进行身份验证

打开 PowerShell 并使用以下命令设置 $clientID 会话变量，将 <your-client-id> 替换为应用注册的客户端 ID。
```
$clientId = <your-client-id>
```
$tenantId设置会话变量。如果选择了仅允许组织中的用户在注册应用程序时登录的选项，请将 tenant-id> 替换为<组织的租户 ID。否则，请将替换为 common。
```
$tenantId = <tenant-id>
```

$graphScopes设置会话变量。

$graphScopes = "user.read mail.read mail.send"

使用以下命令对当前 PowerShell 会话中的用户进行身份验证。
```
# Authenticate the user
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -Scopes $graphScopes -UseDeviceAuthentication
```
提示

如果希望使用交互式浏览器身份验证，请省略 -UseDeviceAuthentication 参数。
打开浏览器并浏览到显示的 URL。输入提供的代码并登录。

重要

浏览到 https://microsoft.com/devicelogin时，请注意登录到浏览器的任何现有 Microsoft 365 帐户。使用浏览器功能（如配置文件、来宾模式或专用模式）确保作为要用于测试的帐户进行身份验证。

完成后，返回到 PowerShell 窗口。运行以下命令以验证经过身份验证的上下文。

# Get the Graph context
Get-MgContext

ClientId              : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
TenantId              : 601faea3-be45-4960-898f-92b379b17cd9
CertificateThumbprint :
Scopes                : {Mail.Read, Mail.Send, openid, profile…}
AuthType              : Delegated
AuthProviderType      : DeviceCodeProvider
CertificateName       :
Account               : MeganB@contoso.com
AppName               : PowerShell Graph Tutorial
ContextScope          : CurrentUser
Certificate           :
PSHostVersion         : 2022.4.1
ClientTimeout         : 00:05:00

获取用户

剩余 12 分钟

在本部分中，你将获得经过身份验证的用户。

在经过身份验证的 PowerShell 会话中，运行以下命令以获取当前上下文。上下文提供用于标识经过身份验证的用户的信息。
```
$context = Get-MgContext
```
运行以下命令，从 Microsoft Graph 获取用户。
```
# Get the authenticated user by UPN
$user = Get-MgUser -UserId $context.Account -Select 'displayName, id, mail, userPrincipalName'
```
提示

可以将开关添加到 -Debug 上一个命令以查看 API 请求和响应。

运行以下命令以输出用户信息。

Write-Host "Hello," $user.DisplayName
# For Work/school accounts, email is in Mail property
# Personal accounts, email is in UserPrincipalName
Write-Host "Email:", ($user.Mail ?? $user.UserPrincipalName)

Hello, Megan Bowen!
Email: MeganB@contoso.com

代码说明

请考虑用于获取经过身份验证的用户的命令。这是一个看似简单的命令，但有一些关键细节需要注意。

访问“me”

命令 Get-MgUser 生成对获取用户 API 的请求。可通过两种方式访问此 API：

GET /me
GET /users/{user-id}

Microsoft Graph PowerShell SDK 不支持 GET /me API 终结点。若要使用 GEt /users/{user-id} 终结点，必须为参数提供值 {user-id} 。在上面的示例中， $context.Account 使用值。此值包含经过身份验证的用户的用户主体名称 (UPN) 。

请求特定属性

函数使用 -Select 命令上的参数来指定它所需的属性集。这会将 $select 查询参数添加到 API 调用。

强类型返回类型

函数从 API 的 JSON 响应返回 MicrosoftGraphUser 反序列化的对象。由于命令使用 -Select，因此只有请求的属性在返回的对象中具有值。所有其他属性将具有默认值。

列出收件箱

剩余 10 分钟

在本部分中，你将在用户的电子邮件收件箱中列出邮件。

在经过身份验证的 PowerShell 会话中 $user ，验证变量是否已设置。
```
PS > $user.DisplayName
Megan Bowen
```

运行以下命令以列出用户的收件箱。

Get-MgUserMailFolderMessage -UserId $user.Id -MailFolderId Inbox -Select `
  "from,isRead,receivedDateTime,subject" -OrderBy "receivedDateTime DESC" `
  -Top 25 | Format-Table Subject,@{n='From';e={$_.From.EmailAddress.Name}}, `
  IsRead,ReceivedDateTime

查看输出。

Subject                                    From                    IsRead ReceivedDateTime
-------                                    ----                    ------ ----------------
Updates from Ask HR and other communities  Contoso Demo on Yammer  False  4/19/2022 10:19:02 PM
Employee Initiative Thoughts               Patti Fernandez         False  4/19/2022 3:15:56 PM
Voice Mail (11 seconds)                    Alex Wilber             False  4/18/2022 2:24:16 PM
Our Spring Blog Update                     Alex Wilber             True   4/18/2022 1:52:03 PM
Atlanta Flight Reservation                 Alex Wilber             False  4/13/2022 2:30:27 AM
Atlanta Trip Itinerary - down time         Alex Wilber             False  4/12/2022 4:46:01 PM

代码说明

考虑用于列出用户收件箱的命令

访问已知邮件文件夹

命令 Get-MgUserMailFolderMessage 生成对列表消息 API 的请求，特别是使用 GET /users/{user-id}/mailFolders/{folder-id}/messages 终结点。使用该终结点，API 仅返回所请求邮件文件夹中的邮件。在这种情况下，由于收件箱是用户邮箱中默认的已知文件夹，因此可通过其已知名称对其进行访问： -MailFolderId Inbox。非默认文件夹的访问方式相同，方法是将已知名称替换为邮件文件夹的 ID 属性。有关可用已知文件夹名称的详细信息，请参阅 mailFolder 资源类型。

访问集合

与上一 Get-MgUser 部分中返回单个对象的命令不同，此方法返回消息集合。 Microsoft Graph 中返回集合的大多数 API 不会在单个响应中返回所有可用结果。相反，它们使用分页返回部分结果，同时为客户端提供请求下一个“页面”的方法。

默认页面大小

使用分页的 API 实现默认页面大小。对于消息，默认值为 10。客户端可以使用 $top 查询参数请求更多 (或更少的 ) 。在 Microsoft Graph PowerShell SDK 中，这是使用 -Top 25 参数完成的。

注意

通过 -Top 传递的值是上限，而不是显式数字。 API 返回一些 消息，最多返回 指定值。

集合排序

函数在 -OrderBy 请求上使用参数来请求按消息接收时间排序的结果， (receivedDateTime 属性) 。它包含DESC关键字 (keyword) 以便先列出最近收到的消息。这会将 $orderby 查询参数添加到 API 调用。

发送邮件

剩余 8 分钟

在本部分中，你将以经过身份验证的用户身份发送电子邮件。

在经过身份验证的 PowerShell 会话中 $user ，验证变量是否已设置。
```
PS > $user.DisplayName
Megan Bowen
```

使用以下命令定义表示发送邮件 API 的请求正文的对象。

$sendMailParams = @{
    Message = @{
        Subject = "Testing Microsoft Graph"
        Body = @{
            ContentType = "text"
            Content = "Hello world!"
        }
        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = ($user.Mail ?? $user.UserPrincipalName)
                }
            }
        )
    }
}

使用以下命令发送消息。
```
Send-MgUserMail -UserId $user.Id -BodyParameter $sendMailParams
```
注意

如果使用 Microsoft 365 开发人员计划中的开发人员租户进行测试，则发送的电子邮件可能未送达，并且可能会收到未送达报告。如果发生这种情况，请通过Microsoft 365 管理中心联系支持人员。
若要验证是否已收到消息，请重复 Get-MgUserMailFolderMessage 上一步中的命令。

代码说明

请考虑用于发送消息的命令。

发送邮件

命令 Send-MgUserMail 生成对发送邮件 API 的请求。

创建对象

与以前只读取数据的 Microsoft Graph 调用不同，此调用会创建数据。若要使用 SDK 执行此操作，请创建一个表示请求正文的对象，设置所需的属性，然后在参数中 BodyParameter 传递它。

可选：添加自己的代码

剩余 5 分钟

在本部分中，你将使用自己的 Microsoft Graph PowerShell SDK 命令。这可能是 Microsoft Graph 文档或 Graph 资源管理器中的代码片段，也可以是你创建的代码片段。此部分是可选的。

选择 API

在 Microsoft Graph 中查找想要尝试的 API。例如，创建事件 API。可以使用 API 文档中的示例之一，在 Graph 资源管理器中自定义 API 请求并使用生成的代码片段，或使用 Find-MgGraphCommand 命令查找相应的命令。

例如，用于创建事件的 API 终结点之一是 POST /users/{id | userPrincipalName}/events。可以使用它查找相应的 PowerShell 命令。

PS > Find-MgGraphCommand -Uri "/users/{id | userPrincipalName}/events" -Method "POST"

   APIVersion: v1.0

Command         Module   Method URI                     OutputType           Permissions           Variants
-------         ------   ------ ---                     ----------           -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent {Calendars.ReadWrite} {Create1, CreateExp…

   APIVersion: beta

Command         Module   Method URI                     OutputType            Permissions           Variants
-------         ------   ------ ---                     ----------            -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent1 {Calendars.ReadWrite} {Create, CreateExp…

输出指示命令 New-MgUserEvent 是相应的命令。

配置权限

查看所选 API 的参考文档 的“权限” 部分，了解支持哪些身份验证方法。例如，某些 API 不支持用户 (委托) 身份验证或个人 Microsoft 帐户。

断开当前会话 (Disconnect-MgGraph) ，并使用参数中的 -Scopes 所需权限重新连接。

提示

-ForceRefresh将参数与命令结合使用Connect-MgGraph可确保应用新配置的权限。

运行命令

现在，你已使用所需的权限进行连接，请运行所选命令。

恭喜！

100% 完成！

你已完成 PowerShell Microsoft Graph 教程。现在，你已有一个可调用 Microsoft Graph 的工作应用，可以试验和添加新功能。

了解如何通过 Microsoft Graph PowerShell SDK 使用仅限应用的身份验证。
访问 Microsoft Graph 概述，查看可以使用 Microsoft Graph 访问的所有数据。