Skip to content

Commit 0b436d9

Browse files
msewawerumsewaweru
committed
Updates to resolve UUF issue and nit edits
1 parent 74e50b6 commit 0b436d9

File tree

3 files changed

+64
-47
lines changed

3 files changed

+64
-47
lines changed

‎microsoftgraph/docs-conceptual/find-mg-graph-command.md

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "Using Find-MgGraphCommand cmdlet"
2+
title: "Use Find-MgGraphCommand cmdlet"
33
description: "Learn how to use the Find-MgGraphCommand to aid in discoverability of cmdlets."
44

55
ms.topic: how-to
@@ -12,22 +12,24 @@ reviewer: maisarissi
1212
#customer intent: As a PowerShell user, I want to use the Find-MgGraphCommand cmdlet to easily discover the API path that a command calls, so that I can efficiently work with Microsoft Graph PowerShell commands and understand the permissions required for each command.
1313
---
1414

15-
# Using Find-MgGraphCommand cmdlet
15+
# Use Find-MgGraphCommand cmdlet
1616

17-
`Find-MgGraphCommand` aims to make it easier for you to discover which API path a command calls, by providing a URI or a command name.
17+
`Find-MgGraphCommand` helps you discover which API path a command calls by providing a URI or command name.
1818

19-
The `Find-MgGraphCommand` cmdlet allows you to:
19+
You can use the `Find-MgGraphCommand` cmdlet to:
2020

2121
- Pass a Microsoft Graph URL (relative and absolute) and get an equivalent Microsoft Graph PowerShell command.
2222
- Pass a command and get the URL it calls.
23-
- Pass a command or URI wildcard (.*) to find all commands that match it.
23+
- Pass a command or URI wildcard, for example `.*`, to find all matching commands.
2424

25-
The output of this cmdlet also includes the permissions required to authenticate the specified cmdlet. For more information on cmdlet permissions, see [Using Find-MgGraphPermission](find-mg-graph-permission.md). Not all cmdlets have the permissions available on running this command. This is an ongoing feature, and permissions will continue to be added.
25+
The output of this cmdlet also includes the permissions required to authenticate the specified cmdlet. For more information on discovering permissions, see [Using Find-MgGraphPermission](find-mg-graph-permission.md), which is a separate cmdlet dedicated to permissions discovery.
2626

27-
The permissions displayed don't show the privilege levels. To learn more, including how to choose permissions, permission type, and what is the most privileged/least privileged permission, use the corresponding API page doc.
27+
The permissions displayed don't indicate privilege levels. For guidance on choosing permissions, understanding permission types, and identifying the most or least privileged permissions, refer to the documentation for the corresponding API page.
2828

2929
## Find Microsoft Graph PowerShell commands by URI
3030

31+
Before using the cmdlet, review the following syntax for reference.
32+
3133
### Syntax
3234

3335
```powershell
@@ -61,10 +63,10 @@ Remove-MgUser Users DELETE /users/{user-id} {DeviceManageme
6163
Update-MgUser Users PATCH /users/{user-id} {DeviceManagementApps.ReadWrite.All, DeviceManagementManagedDevices.ReadWrite.All, DeviceManagementServiceConfig.ReadWrite.All, Directory.AccessAsUser.All...} {Update1, UpdateExpanded1, UpdateViaIdentity1, UpdateViaIdentityExpanded1}
6264
```
6365

64-
>[!Note]
65-
>1. For **-ApiVersion** parameter, there are two possible values: `v1.0` and `beta`.
66-
>1. The **-Method** parameter is only available when using URI to find commands and allows the HTTPs methods such as GET, POST, PUT, PATCH, and DELETE.
67-
>1. The output shown in this article has been shortened for readability.
66+
> [!NOTE]
67+
> - For the **-ApiVersion** parameter, there are two possible values: `v1.0` and `beta`.
68+
> - The **-Method** parameter is only available when using a URI to find commands and allows HTTP methods such as GET, POST, PUT, PATCH, and DELETE.
69+
> - The output shown in this article has been shortened for readability.
6870
6971
## Find Microsoft Graph PowerShell commands by command name
7072

@@ -175,4 +177,7 @@ Get-MgUserActivityHistoryItem CrossDeviceExperiences GET /users
175177

176178
## See also
177179

178-
- [Using Find-MgGraphPermission cmdlet](find-mg-graph-permission.md)
180+
- [Find-MgGraphPermission cmdlet](find-mg-graph-permission.md)
181+
- [Microsoft Graph PowerShell overview](overview.md)
182+
- [Authentication and permissions in Microsoft Graph PowerShell](authentication.md)
183+
- [Microsoft Graph REST API reference](/graph/api/overview)

‎microsoftgraph/docs-conceptual/find-mg-graph-permission.md

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "Using Find-MgGraphPermission cmdlet"
2+
title: "UseFind-MgGraphPermission cmdlet"
33
description: "Learn how to use the Find-MgGraphPermission to discover permissions related to a ___domain."
44

55
ms.topic: how-to
@@ -12,15 +12,16 @@ reviewer: maisarissi
1212
#customer intent: As a Microsoft Graph PowerShell user, I want to find the identifier for a specific permission, so that I can accurately supply the permission-related parameters of commands like New-MgApplication and other application and consent related commands.
1313
---
1414

15-
# Using Find-MgGraphPermission cmdlet
15+
# Use Find-MgGraphPermission cmdlet
1616

17-
The Microsoft Graph PowerShell SDK application requires users to have ___domain knowledge of both the semantics and syntax of Microsoft Graph API permissions used to authorize access to the API. The `Find-MgGraphPermission` cmdlet helps to answer the following questions:
17+
The Microsoft Graph PowerShell SDK requires users to understand both the semantics and syntax of Microsoft Graph API permissions. The `Find-MgGraphPermission` cmdlet helps answer the following questions:
1818

1919
- How do I find the values to supply to the permission-related parameters of commands like `New-MgApplication` and other application and consent related commands?
2020
- What permissions are applicable to a certain ___domain? For example, application.
21-
To use Microsoft Graph PowerShell to access Microsoft Graph, users must sign in to a Microsoft Entra application using the `Connect-MgGraph` command. Use the [Find-MgGraphCommand](find-mg-graph-command.md) to find which permissions to use for a specific cmdlet or API.
2221

23-
Currently, PowerShell commands and scripts have no way of validating user input that refers to permissions or providing an *auto-complete* user experience to help users accurately supply input to commands. This also affects commands or scripts implemented with the Microsoft Graph PowerShell SDK itself.
22+
To use Microsoft Graph PowerShell to access Microsoft Graph, users must sign in to Microsoft Graph using the `Connect-MgGraph` cmdlet. Use the [Find-MgGraphCommand](find-mg-graph-command.md) to find which permissions to use for a specific cmdlet or API.
23+
24+
Currently, PowerShell commands and scripts cannot validate user input that refers to permissions. They also do not provide an *auto-complete* experience to help users supply input accurately. This also affects commands or scripts implemented with the Microsoft Graph PowerShell SDK itself.
2425

2526
## Find permissions related to a given ___domain
2627

@@ -76,4 +77,4 @@ Description : Allows the app to read all applications and service principals
7677

7778
## See also
7879

79-
- [Using Find-MgGraphCommand cmdlet](find-mg-graph-command.md)
80+
- [Find-MgGraphCommand cmdlet](find-mg-graph-command.md)

‎microsoftgraph/docs-conceptual/get-started.md

Lines changed: 40 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,51 @@
11
---
22
title: "Get started with the Microsoft Graph PowerShell SDK"
3-
description: "Get started with the Microsoft Graph PowerShell SDK by using it perform some basic tasks."
3+
description: "Get started with the Microsoft Graph PowerShell SDK by using it to perform some basic tasks."
44

55
author: msewaweru
66
manager: mwongerapk
77
ms.topic: quickstart
8-
ms.date: 03/18/2025
8+
ms.date: 07/23/2025
99
ms.author: eunicewaweru
1010

1111
#customer intent: As a PowerShell user, I want to learn how to use the Microsoft Graph PowerShell SDK, so that I can perform basic tasks using the Microsoft Graph REST API and authenticate with delegated access.
1212
---
1313

1414
# Get started with the Microsoft Graph PowerShell SDK
1515

16-
In this guide, you'll use the Microsoft Graph PowerShell SDK to perform some basic tasks. If you haven't already, [install the SDK](installation.md) before following this guide.
16+
In this Quickstart, you use the Microsoft Graph PowerShell SDK to perform some basic tasks. If you haven't already, [install the SDK](installation.md) before following this guide.
1717

1818
## API version
1919

20-
The SDK contains two modules, Microsoft.Graph and Microsoft.Graph.Beta that call the [Microsoft Graph REST API v1.0](/graph/api/overview?view=graph-rest-1.0&preserve-view=true) and [Microsoft Graph REST API beta](/graph/api/overview?view=graph-rest-beta&preserve-view=true), respectively. Cmdlets are available for the module that is installed.
20+
The SDK contains two modules, Microsoft.Graph and Microsoft.Graph.Beta that call the [Microsoft Graph REST API v1.0](/graph/api/overview?view=graph-rest-1.0) and [Microsoft Graph REST API beta](/graph/api/overview?view=graph-rest-beta), respectively. Cmdlets are available for the module that is installed.
2121

22-
## Authentication
22+
To get started with the SDK, follow these steps:
2323

24-
The PowerShell SDK supports two types of authentication: *delegated access*, and *app-only access*. In this guide, you'll use delegated access to sign in as a user, grant consent to the SDK to act on your behalf, and call Microsoft Graph.
24+
1. Install either the `Microsoft.Graph` or `Microsoft.Graph.Beta` module, depending on which API version you want to use.
25+
2. Import the module into your PowerShell session.
26+
3. Authenticate using the appropriate permissions.
27+
4. Begin making calls to Microsoft Graph using the available cmdlets.
2528

26-
For details on using app-only access for unattended scenarios, see [Use app-only authentication with the Microsoft Graph PowerShell SDK](app-only.md).
29+
## Authentication
30+
31+
The PowerShell SDK supports two types of authentication: [*delegated access*](/graph/auth/auth-concepts#delegated-access-access-on-behalf-of-a-user), and [*app-only access*](/graph/auth/auth-concepts#app-only-access-access-without-a-user). In this guide, you use delegated access to sign in as a user, grant consent to the SDK to act on your behalf, and call Microsoft Graph.
32+
33+
For more details on using app-only access for unattended scenarios, see [Use app-only authentication with the Microsoft Graph PowerShell SDK](app-only.md).
2734

2835
### Determine required permission scopes
2936

30-
Each API in the Microsoft Graph is protected by one or more permission scopes. The user logging in must consent to one of the required scopes for the APIs you plan to use. In this example, we'll use the following APIs.
37+
Each API in the Microsoft Graph is protected by one or more permission scopes. The user logging in must consent to one of the required scopes for the APIs you plan to use. In this example, we use the following APIs.
3138

3239
- [List users](/graph/api/user-list?view=graph-rest-1.0&preserve-view=true) to find the user ID of the logged-in user.
3340
- [List joinedTeams](/graph/api/user-list-joinedteams?view=graph-rest-1.0&preserve-view=true) to get the Teams the user is a member of.
3441
- [List channels](/graph/api/channel-list?view=graph-rest-1.0&preserve-view=true) to get the channels in a Team.
3542
- [Send message](/graph/api/channel-post-messages?view=graph-rest-1.0&preserve-view=true) to send a message to a Team's channel.
3643

37-
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 account with the **Application Administrator** or **Cloud Application Administrator** role to grant consent. For more information, see [Microsoft Entra built-in roles](/entra/identity/role-based-access-control/permissions-reference).
44+
The `User.Read.All` permission scope will enable the first two calls, and the `Group.ReadWrite.All` scope will enable the rest. Granting consent for these permissions typically requires an account with the **Privileged Role Administrator** role. For more information, see [Microsoft Entra built-in roles](/entra/identity/role-based-access-control/permissions-reference).
3845

39-
#### Using Find-MgGraphCommand to find required permissions
46+
#### Use Find-MgGraphCommand to find required permissions
4047

41-
The `Find-MgGraphCommand` cmdlet can be used to discover the required permissions for another cmdlet. For example, to see all permissions that can be used to call `Get-MgUser`, run;
48+
The `Find-MgGraphCommand` cmdlet can be used to discover the required permissions for another cmdlet. For example, to see all permissions that can be used to call `Get-MgUser`, run:
4249

4350
```powershell
4451
Find-MgGraphCommand -command Get-MgUser | Select -First 1 -ExpandProperty Permissions
@@ -56,36 +63,36 @@ User.ReadWrite.All True Read and write all users' f
5663

5764
This output has been shortened for readability.
5865

59-
For more information on using this cmdlet, see [Using Find-MgGraphCommand](find-mg-graph-command.md).
66+
For more information on using this cmdlet, see [Use Find-MgGraphCommand](find-mg-graph-command.md).
6067

6168
### Sign in
6269

63-
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.
70+
Use the `Connect-MgGraph` command to sign in with the required scopes. You need to sign in with an admin account to consent to the required scopes.
6471

6572
```powershell
6673
Connect-MgGraph -Scopes "User.Read.All","Group.ReadWrite.All"
6774
```
6875

69-
The command prompts you to go to a web page to sign in with your credentials. Once you've done that, the command indicates success with a `Welcome To Microsoft Graph!` message. You only need to sign in once per session.
76+
The command prompts you to go to a web page to sign in with your credentials. Once you've done that, the command indicates success with a `Welcome To Microsoft Graph!` message. You only need to sign in once per PowerShell session (that is, until you close and reopen your PowerShell window or call `Disconnect-MgGraph`).
7077

7178
> [!TIP]
7279
> You can add additional permissions by repeating the `Connect-MgGraph` command with the new permission scopes.
7380
7481
## Call Microsoft Graph
7582

76-
Now that you're signed in, you can start making calls to Microsoft Graph.
83+
After signing in, you can begin making calls to Microsoft Graph.
7784

7885
[!INCLUDE [aad-advanced-queries-note](../includes/aad-advanced-queries-note.md)]
7986

80-
### Get the signed-in user
87+
### Get a user
8188

82-
In this section, you'll locate the signed-in user and get their user Id. You'll need the user Id as a parameter to the other commands you'll run later. Start by running the following command.
89+
In this section, you will identify a user in the list returned by `Get-MgUser` and store their information in the `$user` variable, which will be used as a parameter in subsequent commands. Start by running the following command.
8390

8491
```powershell
8592
Get-MgUser
8693
```
8794

88-
This command outputs a listing of users in your Microsoft 365 organization.
95+
This command outputs a listing of users in your Microsoft 365 organization; in organizations with many users, the output may be limited or paginated, so consider using filtering to locate specific users.
8996

9097
```powershell
9198
Id DisplayName Mail UserPrincipalName
@@ -101,35 +108,37 @@ ce73bdb5-bf12-405e-ab85-40122fdd6eb7 Brian Johnson (TAILSPIN) [email protected]
101108
df1347a3-7ce7-4b4d-8aab-7c65b5c907b9 Cameron White CameronW@contoso…
102109
```
103110

104-
You can use an [OData filter](use-query-parameters.md#filter-parameter) to help locate the specific user you want. Run the following command, replacing `Megan Bowen` with the display name of the user you signed in with.
111+
An OData filter is a query option that allows you to filter results based on specific property values. You can use an [OData filter](use-query-parameters.md#filter-parameter) to help locate the specific user you want. OData filters allow you to query data using expressions such as `property eq 'value'`; see [OData query parameters overview](/graph/query-parameters) for more details on the syntax.
112+
113+
Run the following command, replacing `[email protected]` with the user principal name of an actual user in your organization that you want to use.
105114

106115
```powershell
107-
$user = Get-MgUser -Filter "displayName eq 'Megan Bowen'"
116+
$user = Get-MgUser -Filter "userPrincipalName eq '[email protected]'"
108117
```
109118

110-
Verify that worked by entering the following.
119+
Verify the command worked by entering the following command.
111120

112121
```powershell
113122
$user.DisplayName
114123
```
115124

116125
### List the user's joined teams
117126

118-
Now use the user's Id as a parameter to the `Get-MgUserJoinedTeam` command.
127+
Use the value of `$user.Id` as the `-UserId` parameter in the `Get-MgUserJoinedTeam` command.
119128

120129
```powershell
121130
Get-MgUserJoinedTeam -UserId $user.Id
122131
```
123132

124-
Just like the `Get-MgUser` command, this command gives a list of teams. Select one of the user's joined teams and copy its `Id`, to use in the next command.
133+
Like `Get-MgUser`, this command returns a list of teams. Select one of the user's joined teams and copy its `Id` to use in the next command.
125134

126135
```powershell
127136
$team = Get-MgTeam -TeamId ID_FROM_PREVIOUS_STEP
128137
```
129138

130139
### List team channels
131140

132-
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.
141+
Now use the team's Id as a parameter to the `Get-MgTeamChannel` command. First, list all channels, then filter the list to get the specific channel you want.
133142

134143
```powershell
135144
Get-MgTeamChannel -TeamId $team.Id
@@ -138,27 +147,29 @@ $channel = Get-MgTeamChannel -TeamId ID_FROM_PREVIOUS_STEP -Filter "displayName
138147

139148
### Send a message
140149

141-
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.
150+
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.
142151

143152
```powershell
144153
New-MgTeamChannelMessage -TeamId $team.Id -ChannelId $channel.Id -Body @{ Content="Hello World" }
145154
```
146155

147-
This command differs from the previous commands you used. Instead of querying data, it's creating something. In Microsoft Graph, this command translates to an HTTP `POST`, and it requires an object in the body of that post. In this case, the object is a [chatMessage](/graph/api/resources/chatmessage). 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.
156+
This command differs from the previous commands you used. Instead of querying data, it's creating something. In Microsoft Graph, this command translates to an HTTP `POST`, and it requires an object in the body of that post. In this case, the object is a [chatMessage](/graph/api/resources/chatmessage). The `-Body` parameter is a hashtable that maps to the `body` property of the `chatMessage` resource. 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.
148157

149158
```powershell
150159
New-MgTeamChannelMessage -TeamId $team.Id -ChannelId $channel.Id -Body @{ Content="Hello World" } -Importance "urgent"
151160
```
152161

153162
### Sign out
154163

155-
Use the `Disconnect-MgGraph` command to sign out.
164+
Use the `Disconnect-MgGraph` command to sign out. This ends your current session and revokes the authentication token for the active PowerShell session, ensuring your credentials are no longer available until you sign in again.
156165

157166
```powershell
158167
Disconnect-MgGraph
159168
```
160169

161170
## Next steps
162171

163-
- [Learn how to navigate the SDK](navigating.md).
164-
- [Use app-only authentication with the Microsoft Graph PowerShell SDK](app-only.md).
172+
Now that you've completed the basic tasks, explore the following resources to deepen your understanding and expand your usage of the Microsoft Graph PowerShell SDK:
173+
174+
- [Learn how to navigate the SDK](navigating.md)
175+
- [Use app-only authentication with the Microsoft Graph PowerShell SDK](app-only.md)

0 commit comments

Comments
 (0)