Microsoft Graph PowerShell SDK 入门Get started with the Microsoft Graph PowerShell SDK

在本指南中,你将使用 Microsoft Graph PowerShell SDK 执行一些基本任务。In this guide you'll use the Microsoft Graph PowerShell SDK to perform some basic tasks. 如果尚未安装 SDK,请在遵循本指南之前进行安装。If you haven't already installed the SDK, please do so before following this guide.

API 版本API version

默认情况下,SDK 使用Microsoft Graph REST API v1.0。By default, the SDK uses the Microsoft Graph REST API v1.0. 可以使用命令更改 Select-MgProfile 此参数。You can change this by using the Select-MgProfile command.

Select-MgProfile -Name "beta"

身份验证Authentication

PowerShell SDK 支持两种类型的身份验证:委派访问和仅应用访问。The PowerShell SDK supports two types of authentication: delegated access, and app-only access. 在本指南中,你将使用委派访问权限以用户的名义登录,同意 SDK 代表你操作,并调用 Microsoft Graph。In this guide, you will use delegated access to login as a user, grant consent to the SDK to act on your behalf, and call the Microsoft Graph.

有关将仅应用访问用于无人参与方案的详细信息,请参阅将仅应用身份验证与 Microsoft Graph PowerShell SDK 一同使用For details on using app-only access for unattended scenarios, see Use app-only authentication with the Microsoft Graph PowerShell SDK.

确定所需的权限范围Determine required permission scopes

Microsoft Graph 中的每个 API 都受一个或多个权限范围保护。Each API in the Microsoft Graph is protected by one or more permission scopes. 用户登录必须同意计划使用的 API 所需的范围之一。The user logging in must consent to one of the required scopes for the APIs you plan to use. 此示例中,我们将使用以下 API。In this example, we'll use the following APIs.

权限 User.Read.All 范围将启用前两个调用, Group.ReadWrite.All 该范围将启用其余调用。The User.Read.All permission scope will enable the first two calls, and the Group.ReadWrite.All scope will enable the rest. 这些权限需要管理员帐户。These permissions require an admin account.

登录Sign in

使用 Connect-MgGraph 此命令使用所需范围登录。Use the Connect-MgGraph command to sign in with the required scopes. 你将需要使用管理员帐户登录,以同意所需的作用域。You'll need to sign in with an admin account to consent to the required scopes.

Connect-MgGraph -Scopes "User.Read.All","Group.ReadWrite.All"

该命令将提示您转到网页以使用设备代码登录。The command prompts you to go to a web page to sign in using a device code. 完成后,该命令会通过一条消息指示 Welcome To Microsoft Graph! 是否成功。Once you've done that, the command indicates success with a Welcome To Microsoft Graph! message. 每个会话只需执行一次此操作。You only need to do this once per session.

提示

您可以通过使用新的权限范围重复该命令 Connect-MgGraph 来添加其他权限。You can add additional permissions by repeating the Connect-MgGraph command with the new permission scopes.

调用 Microsoft GraphCall Microsoft Graph

现在,你已登录,可以开始调用 Microsoft Graph。Now that you're signed in, you can start making calls to Microsoft Graph.

获取登录用户Get the signed-in user

在此部分中,你将找到登录用户并获取其用户 ID。In this section you'll locate the signed-in user and get her user ID. 你将需要该参数用作以后将使用的其他命令的参数。You'll need that to use as a parameter to the other commands you'll use later. 首先运行以下命令。Start by running the following command.

Get-MgUser

这将输出 Microsoft 365 组织中用户列表。This outputs a listing of users in your Microsoft 365 organization.

Id                                   DisplayName              Mail                                  UserPrincipalName
--                                   -----------              ----                                  -----------------
88d1ba68-8ff5-4de2-90ed-768c00abcfae Conf Room Adams          Adams@contoso.onmicrosoft.com         Adams@contoso.…
3103c7b9-cfe6-4cd3-a696-f88909b9a609 Adele Vance              AdeleV@contoso.OnMicrosoft.com        AdeleV@contoso…
da3a885e-2d97-41de-9347-5271ef321b58 MOD Administrator        admin@contoso.OnMicrosoft.com         admin@contoso.…
e0c6ee40-e105-476d-9597-acd061d21fcb Alex Wilber              AlexW@contoso.OnMicrosoft.com         AlexW@contoso.…
17c6bdee-8ed3-49af-a65e-71b64cca8382 Allan Deyoung            AllanD@contoso.OnMicrosoft.com        AllanD@contoso…
e5b78950-27cd-4f01-b083-eab4da97ca6a Conf Room Baker          Baker@contoso.onmicrosoft.com         Baker@contoso.…
40467725-1a58-495d-9e2f-5970c6306d8d Bianca Pisani                                                  BiancaP@contoso…
ce73bdb5-bf12-405e-ab85-40122fdd6eb7 Brian Johnson (TAILSPIN) BrianJ@contoso.onmicrosoft.com        BrianJ@contoso…
df1347a3-7ce7-4b4d-8aab-7c65b5c907b9 Cameron White                                                  CameronW@contoso…

可以使用 OData 筛选器来帮助 找到您想要的特定用户。You can use an OData filter to help locate the specific user you want. 运行以下命令,替换为 Megan Bowen 显示名称登录的用户的用户名。Run the following command, replacing Megan Bowen with the display name of the user you signed in with.

$user = Get-MgUser -Filter "displayName eq 'Megan Bowen'"

通过输入以下内容验证是否有效。Verify that worked by entering the following.

$user.DisplayName

列出用户加入的 TeamsList the user's joined Teams

现在,使用用户的 ID 作为命令 Get-MgUserJoinedTeam 的参数。Now use the user's ID as a parameter to the Get-MgUserJoinedTeam command.

Get-MgUserJoinedTeam -UserId $user.Id

与命令 Get-MgUser 一样,这会提供 Teams 列表。Just like the Get-MgUser command, this gives a list of Teams. 选择用户加入的 Teams 之一,并使用其 DisplayName 筛选列表。Select one of the user's joined Teams and use its DisplayName to filter the list.

$team = Get-MgUserJoinedTeam -UserId $user.Id -Filter "displayName eq 'Sales and Marketing'"

列出团队频道List Team channels

现在,使用团队 ID 作为命令的参数,遵循列出所有频道的类似模式,然后筛选列表,获取 Get-MgTeamChannel 您想要的特定频道。Now use the Team's ID as a parameter to the Get-MgTeamChannel command, following a similar pattern of listing all channels, then filtering the list to get the specific channel you want.

Get-MgTeamChannel -TeamId $team.Id
$channel = Get-MgTeamChannel -TeamId $team.Id -Filter "displayName eq 'General'"

发送邮件Send a message

现在,你同时拥有团队 ID 和频道 ID,你可以向频道发布消息。Now that you have both the Team ID and the channel ID, you can post a message to the channel. 使用以下命令发送邮件。Use the following command to send the message.

New-MgTeamChannelMessage -TeamId $team.Id -ChannelId $channel.Id -Body @{ Content="Hello World" }

此命令与之前使用的命令不同。This command differs from the previous commands you used. 它实际上正在创建一些内容,而不只是查询数据。Instead of just querying data, it's actually creating something. 在 Microsoft Graph 中,这会转换为 HTTP,并且它需要该文章正文 POST 中的对象。In Microsoft Graph, this translates to an HTTP POST, and it requires an object in the body of that post. 在这种情况下,对象是 chatMessageIn this case, the object is a chatMessage. 请注意, -Body 该命令的参数映射到 body 上的属性 chatMessageNote that the -Body parameter to the command maps to the body property on chatMessage. 其他属性的映射方式类似,因此可以更改发送的邮件。Other properties are mapped in a similar way, so you can change the message you send. 例如,若要发送紧急邮件,请使用以下命令。For example, to send an urgent message use the following command.

New-MgTeamChannelMessage -TeamId $team.Id -ChannelId $channel.Id -Body @{ Content="Hello World" } -Importance "urgent"

注销Sign out

使用 Disconnect-MgGraph 命令注销。Use the Disconnect-MgGraph command to sign out.

Disconnect-MgGraph

后续步骤Next steps