使用 Microsoft Graph 生成 PowerShell 脚本
本教程介绍如何生成一个 PowerShell 脚本,该脚本使用 Microsoft Graph API 代表用户访问数据。
备注
若要了解如何使用 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 编写。 本指南中的步骤可能适用于其他版本,但尚未测试。
在门户中注册该应用
在本练习中,你将在 Azure Active Directory 中注册一个新应用程序以启用 用户身份验证。 可以使用 Microsoft Entra 管理中心或使用 Microsoft Graph PowerShell SDK 注册应用程序。
注册应用程序进行用户身份验证
在本部分中,你将注册一个支持使用 设备代码流进行用户身份验证的应用程序。
备注
为 Microsoft Graph PowerShell SDK 注册应用程序以进行身份验证是可选的。 SDK 具有自己的应用程序注册和相应的客户端 ID。 但是,使用自己的应用程序 ID 可以更好地控制特定 PowerShell 脚本的权限范围。
打开浏览器,导航到 Microsoft Entra 管理中心 ,并使用全局管理员帐户登录。
在左侧导航栏中选择“Microsoft Entra ID”,依次展开“标识”、“应用程序”和“应用注册”。
选择“新注册”。 输入应用程序的名称,例如
Graph User Auth Tutorial
。根据需要设置 支持的帐户类型 。 选项包括:
选项 谁可以登录? 仅限此组织目录中的帐户 仅限 Microsoft 365 组织中的用户 任何组织目录中的帐户 任何Microsoft 365 组织中的用户 (工作或学校帐户) 任何组织目录中的帐户...和个人Microsoft帐户 任何Microsoft 365 组织中的用户 (工作或学校帐户) 和个人Microsoft帐户 保留“重定向 URI”为空。
选择“注册”。 在应用程序的 “概述 ”页上,复制 “应用程序 (客户端) ID ”的值并保存它,下一步将需要它。 如果 为此组织目录中的“帐户”选择“仅 支持 帐户类型”,则还要复制 “目录 (租户) ID 并保存它。
选择“管理”下的“身份验证”。 找到 “高级设置” 部分,将 “允许公共客户端流” 切换开关更改为 “是”,然后选择“ 保存”。
备注
请注意,你未对应用注册配置任何 Microsoft Graph 权限。 这是因为此示例使用 动态同意 请求用户身份验证的特定权限。
添加用户身份验证
在本部分中,你将作为 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
获取用户
在本部分中,你将获得经过身份验证的用户。
在经过身份验证的 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
,因此只有请求的属性在返回的对象中具有值。 所有其他属性将具有默认值。
列出收件箱
在本部分中,你将在用户的电子邮件收件箱中列出邮件。
在经过身份验证的 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
关键字,以便首先列出最近收到的消息。 这会将 $orderby 查询参数 添加到 API 调用。
发送邮件
在本部分中,你将以经过身份验证的用户身份发送电子邮件。
在经过身份验证的 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
传递它。
可选:添加自己的代码
在本部分中,你将使用自己的 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
可确保应用新配置的权限。
运行命令
现在,你已使用所需的权限进行连接,请运行所选命令。
恭喜!
已完成 PowerShell Microsoft Graph 教程。 现在,你已有一个可调用 Microsoft Graph 的工作应用,可以试验和添加新功能。
- 了解如何通过 Microsoft Graph PowerShell SDK 使用 仅限应用的身份验证 。
- 访问 Microsoft Graph 概述 ,查看可以使用 Microsoft Graph 访问的所有数据。
你有关于此部分的问题? 如果有,请向我们提供反馈,以便我们对此部分作出改进。