Navigating the Microsoft Graph PowerShell SDK

  • [アーティクル]

The Microsoft Graph API is huge, and it's growing all the time. Therefore, the number of commands in the Microsoft Graph PowerShell SDK is also large. Finding the right command for what you want to achieve can be challenging, especially if you're not already familiar with Microsoft Graph. Let's look at some ways to help find a particular command.

Note

Some requests for Azure Active Directory resources require the use of advanced query capabilities. If you get a response indicating a bad request, unsupported query, or a response that includes unexpected results, including the $count query parameter and ConsistencyLevel header may allow the request to succeed. For details and examples, see Advanced query capabilities on Azure AD directory objects.

Command naming conventions

The commands in the SDK are generated directly from the REST API, so the names are influenced by the API. You don't have to understand the details of the API to use the Microsoft Graph PowerShell SDK, but it helps to understand the naming convention.

PowerShell commands are named using a verb-noun pair, such as Get-Command or Update-List. Let's start with the verb.

Command verbs

For basic REST operations, the verb is determined by the HTTP method used for the API.

HTTP method Command verb Example
GET Get Get-MgUser API reference
POST New New-MgUserMessage API reference
PUT New New-MgTeam API reference
PATCH Update Update-MgUserEvent API reference
DELETE Remove Remove-MgDriveItem API reference

For functions and actions, it's a little more complicated. APIs in Microsoft Graph that are implemented as OData functions or actions are typically named with at least a verb. The corresponding command's verb is based on the verb in the function or action name. However, command verbs in PowerShell have to conform to specific naming rules, which can result in nonintuitive name-to-command mappings.

Let's look at some examples. The getSchedule API uses get, and Get is an approved PowerShell verb, so its command is Get-MgUserCalendarSchedule. The cancel API on an event on the other hand, uses a nonapproved verb cancel. The approved verb for canceling or discontinuing something is Stop, so the command is Stop-MgUserEvent. Finally, the snoozeReminder API's verb, snooze, has no PowerShell-approved equivalent. For APIs like that, the SDK uses the verb Invoke, so that API's command is Invoke-MgSnoozeUserEventReminder.

Note

For Beta cmdlets add a Beta prefix before the resource. For example, the beta version of the Get-MgUser cmdlet is Get-MgBetaUser.

Command nouns

By now you may have noticed that all nouns in the SDK's commands start with Mg. This prefix helps to avoid naming conflicts with other PowerShell modules. With that in mind, it should make sense that a command like Get-MgUser is used to get a user. Following PowerShell convention, even though the noun is singular, those same commands can return multiple results if no specific instance is requested.

But what about commands like Get-MgUserMessage or Get-MgUserMailFolderMessage? Both of these commands get a message object, so why not Get-MgMessage? The answer comes from the get message API.

Look at the HTTP requests for this API. If you ignore the requests with /me in the URL, there are two other ways to call this API.

GET /users/{id | userPrincipalName}/messages/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}

The paths match to the nouns. For the first form, you start with users, then messages, so the command is Get-MgUserMessage. In the second form, you start with users, then mailFolders, then messages, so the command is Get-MgUserMailFolderMessage.

Another way of looking at this command is asking what owns or contains what. The user owns mail folders, and mail folders contain messages. Add the prefix and you get Get-MgUserMailFolderMessage.

Use Find-MgGraphCommand to discover which API path a command calls by providing a URI or a command name.

Listing parameters

After you've found the right command, you can examine all the available parameters by using the Get-Help command. For example, the following command lists all the available parameters for the Get-MgUser command.

Get-Help Get-MgUser -Detailed

Finding available commands

Sometimes just knowing the naming conventions isn't enough to guess the right command. In this case, you can use the Get-Command command to search the available commands in the SDK. For example, if you're looking for commands related to Microsoft Teams, you can run the following command.

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

Next steps