Navegar pelo SDK do Microsoft Graph PowerShellNavigating the Microsoft Graph PowerShell SDK

A API do Microsoft Graph é imensa e está crescendo o tempo todo.The Microsoft Graph API is huge, and it's growing all the time. Por causa disso, o número de comandos no SDK do Microsoft Graph PowerShell também é muito grande.Because of this, the number of commands in the Microsoft Graph PowerShell SDK is also very large. Encontrar o comando certo para o que você deseja obter pode ser desafiador, especialmente se você ainda não estiver familiarizado com o Microsoft Graph.Finding the right command for what you want to achieve can be challenging, especially if you're not already familiar with Microsoft Graph. Vamos dar uma olhada em algumas maneiras de ajudar a localizar um comando específico.Let's look at some ways to help find a particular command.

Convenções de nomenclatura de comandosCommand naming conventions

Os comandos no SDK são gerados diretamente da API REST, de forma que os nomes são influenciados pela API.The commands in the SDK are generated directly from the REST API, so the names are influenced by the API. Você não precisa entender os detalhes da API para usar este SDK, mas ajuda a entender a Convenção de nomenclatura.You don't have to understand the details of the API to use this SDK, but it helps to understand the naming convention.

Os comandos do PowerShell são nomeados usando um par verbo-substantivo, como Get-Command ou Update-List .PowerShell commands are named using a verb-noun pair, such as Get-Command or Update-List. Vamos começar com o verbo.Let's start with the verb.

Verbos de comandoCommand verbs

Para operações REST básicas, o verbo é determinado pelo método HTTP usado para a API.For basic REST operations, the verb is determined by the HTTP method used for the API.

Método HTTPHTTP method Verbo de comandoCommand verb ExemploExample
OBTERGET ObterGet Get-MgUser Referência da APIGet-MgUser API reference
POSTARPOST NovoNew New-MgUserMessage Referência da APINew-MgUserMessage API reference
PUTPUT NovoNew New-MgTeam Referência da APINew-MgTeam API reference
PATCHPATCH AtualizarUpdate Update-MgUserEvent Referência da APIUpdate-MgUserEvent API reference
EXCLUIRDELETE RemoverRemove Remove-MgDriveItem Referência da APIRemove-MgDriveItem API reference

Para funções e ações, é um pouco mais complicado.For functions and actions, it's a little more complicated. As APIs no Microsoft Graph que são implementadas como funções ou ações de OData normalmente são nomeadas com pelo menos um verbo.APIs in Microsoft Graph that are implemented as OData functions or actions are typically named with at least a verb. O verbo do comando correspondente é baseado no verbo no nome da função ou da ação.The corresponding command's verb is based on the verb in the function or action name. No entanto, os verbos de comando no PowerShell têm que estar em conformidade com as regras de nomenclaturaespecíficas, portanto, isso pode resultar em mapeamentos de nome para comando não intuitivos.However, command verbs in PowerShell have to conform to specific naming rules, so this can result in non-intuitive name-to-command mappings.

Vamos ver alguns exemplos.Let's look at some examples. A API getschedule usa get e Get é um verbo aprovado do PowerShell, portanto, é o comando Get-MgUserCalendarSchedule .The getSchedule API uses get, and Get is an approved PowerShell verb, so it's command is Get-MgUserCalendarSchedule. A API de cancelamento em um evento por outro lado, usa um verbo não aprovado cancel .The cancel API on an event on the other hand, uses a non-approved verb cancel. O verbo aprovado para cancelamento ou descontinuação de algo é Stop , portanto, é o comando Stop-MgUserEvent .The approved verb for cancelling or discontinuing somethign is Stop, so it's command is Stop-MgUserEvent. Por fim, o verbo da API snoozeReminder , snooze , não tem nenhum equivalente aprovado no PowerShell.Finally, the snoozeReminder API's verb, snooze, has no PowerShell-approved equivalent. Para a API como essa, o SDK usa o verbo Invoke , para que o comando da API seja Invoke-MgSnoozeUserEventReminder .For API's like that, the SDK uses the verb Invoke, so that API's command is Invoke-MgSnoozeUserEventReminder.

Substantivos de comandoCommand nouns

Agora você pode ter notado que todos os substantivos nos comandos do SDK começam com Mg .By now you may have noticed that all nouns in the SDK's commands start with Mg. Esse prefixo ajuda a evitar conflitos de nomenclatura com outros módulos do PowerShell.This prefix helps to avoid naming conflicts with other PowerShell modules. Com isso em mente, deve fazer sentido que os comandos como Get-MgUser são usados para obter um usuário.With that in mind, it should make sense that commands like Get-MgUser are used to get a user. E, seguindo a Convenção do PowerShell, mesmo que o substantivo seja singular, esses mesmos comandos podem retornar vários resultados, caso nenhuma instância específica seja solicitada.And following PowerShell convention, even though the noun is singular, those same commands can return multiple results if no specific instance is requested.

Mas e os comandos como Get-MgUserMessage ou Get-MgUserMailFolderMessage ?But what about commands like Get-MgUserMessage or Get-MgUserMailFolderMessage? Ambos são um objeto Message , então por quê não Get-MgMessage ?Both of these get a message object, so why not Get-MgMessage? A resposta vem da API de mensagens Get.The answer comes from the get message API.

Observe as solicitações HTTP para esta API.Look at the HTTP requests for this API. Ignorando as solicitações com /me na URL, há duas outras maneiras de chamar esta API.Ignoring 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}

Os caminhos correspondem aos substantivos.The paths match to the nouns. Para o primeiro formulário, comece com users e, em seguida messages , o comando é Get-MgUserMessage .For the first form, you start with users, then messages, so the command is Get-MgUserMessage. No segundo formulário, comece com users , depois mailFolders , as mensagens, portanto, o comando é Get-MgUserMailFolderMessage .In the second form, you start with users, then mailFolders, then messages, so the command is Get-MgUserMailFolderMessage.

Outra maneira de observar isso é o que é proprietário ou contém o que.Another way of looking at this is what owns or contains what. O usuário possui pastas de email e as pastas de email contêm mensagens.The user owns mail folders, and mail folders contain messages. Adicione o prefixo e você obtém Get-MgUserMailFolderMessage .Add the prefix and you get Get-MgUserMailFolderMessage.

Listando parâmetrosListing parameters

Depois de encontrar o comando certo, você pode examinar todos os parâmetros disponíveis usando o Get-Help comando.After you've found the right command, you can examine all the available parameters by using the Get-Help command. Por exemplo, o comando a seguir lista todos os parâmetros disponíveis para o Get-MgUser comando.For example, the following command lists all the available parameters for the Get-MgUser command.

Get-Help Get-MgUser -Detailed

Localizando comandos disponíveisFinding available commands

Às vezes, apenas conhecer as convenções de nomenclatura não é suficiente para adivinhar o comando correto.Sometimes just knowing the naming conventions isn't enough to guess the right command. Nesse caso, você pode usar o Get-Command comando para pesquisar os comandos disponíveis no SDK.In this case, you can use the Get-Command command to search the available commands in the SDK. Por exemplo, se estiver procurando por comandos relacionados ao Microsoft Teams, você poderá executar o comando a seguir.For example, if you're looking for commands related to Microsoft Teams, you can run the following command.

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