Criar scripts do PowerShell com o Microsoft Graph
Este tutorial ensina como criar um script do PowerShell que usa o microsoft API do Graph para acessar dados em nome de um usuário.
Observação
Para saber como usar o Microsoft Graph para acessar dados usando autenticação somente aplicativo, confira este tutorial de autenticação somente aplicativo.
Neste tutorial, você vai:
Dica
Como alternativa a seguir este tutorial, você pode baixar o código concluído por meio da ferramenta de início rápido , que automatiza o registro e a configuração do aplicativo. O código baixado funciona sem nenhuma modificação necessária.
Você também pode baixar ou clonar o repositório GitHub e seguir as instruções no README para registrar um aplicativo e configurar o projeto.
Pré-requisitos
Antes de iniciar este tutorial, você deve ter o PowerShell instalado em seu computador de desenvolvimento. O PowerShell 5.1 é o requisito mínimo, mas o PowerShell 7 é recomendado.
Você também deve ter uma conta de trabalho ou de estudante da Microsoft com uma caixa de correio Exchange Online. Se você não tiver um locatário do Microsoft 365, poderá se qualificar para um por meio do Programa de Desenvolvedores do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.
Observação
Este tutorial foi escrito com o PowerShell 7.2.2 e o SDK do Microsoft Graph PowerShell versão 1.9.5. As etapas neste guia podem funcionar com outras versões, mas isso não foi testado.
Registrar o aplicativo no portal
Neste exercício, você registrará um novo aplicativo no Azure Active Directory para habilitar a autenticação do usuário. Você pode registrar um aplicativo usando o centro de administração do Azure Active Directory ou usando o SDK do Microsoft Graph PowerShell.
Registrar aplicativo para autenticação de usuário
Nesta seção, você registrará um aplicativo que dá suporte à autenticação do usuário usando o fluxo de código do dispositivo.
Observação
O registro de um aplicativo para autenticação de usuário para o SDK do Microsoft Graph PowerShell é opcional. O SDK tem seu próprio registro de aplicativo e a ID do cliente correspondente. No entanto, usar sua própria ID de aplicativo permite um maior controle sobre escopos de permissão para um script específico do PowerShell.
Abra um navegador e navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta de trabalho ou de estudante.
Selecione Azure Active Directory na navegação esquerda e selecione Registros de aplicativos em Gerenciar.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo,
Graph User Auth Tutorial
.Defina tipos de conta com suporte conforme desejado. As opções são:
Opção Quem pode entrar? Contas apenas neste diretório organizacional Somente usuários em sua organização do Microsoft 365 Contas em qualquer diretório organizacional Usuários em qualquer organização do Microsoft 365 (contas corporativas ou escolares) Contas em qualquer diretório organizacional... e contas pessoais da Microsoft Usuários em qualquer organização do Microsoft 365 (contas corporativas ou escolares) e contas pessoais da Microsoft Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Visão geral do aplicativo, copie o valor da ID do aplicativo (cliente) e salve-o, você precisará dele na próxima etapa. Se você escolheu Contas neste diretório organizacional apenas para tipos de conta com suporte, copie também a ID do Diretório (locatário) e salve-a.
Selecione Autenticação em Gerenciar. Localize a seção Configurações avançadas e altere a alternância Permitir fluxos de cliente público para Sim e escolha Salvar.
Observação
Observe que você não configurou nenhuma permissão do Microsoft Graph no registro do aplicativo. Isso ocorre porque o exemplo usa o consentimento dinâmico para solicitar permissões específicas para autenticação do usuário.
Adicionar autenticação de usuário
Nesta seção, você autenticará uma sessão do PowerShell como usuário do Microsoft Graph. Isso é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph.
O SDK do Microsoft Graph PowerShell fornece dois métodos de autenticação para autenticação do usuário: autenticação interativa do navegador e do código do dispositivo. A autenticação interativa do navegador usa o navegador padrão de um dispositivo para permitir que o usuário entre. A autenticação de código do dispositivo permite a autenticação em ambientes que não têm um navegador padrão. Neste exercício, você usará a autenticação de código do dispositivo.
Importante
Se você ainda não tiver o SDK do Microsoft Graph PowerShell instalado, instale-o agora antes de prosseguir.
Autenticar o usuário
Abra o PowerShell e use o comando a seguir para definir a
$clientID
variável de sessão, substituindo <a id> do cliente pela ID do cliente do registro do aplicativo.$clientId = <your-client-id>
Defina a variável de
$tenantId
sessão. Se você escolheu a opção para permitir apenas que os usuários em sua organização entrem ao registrar seu aplicativo, substitua <a ID> do locatário pela ID do locatário da sua organização. Caso contrário, substitua porcommon
.$tenantId = <tenant-id>
Defina a variável de
$graphScopes
sessão.$graphScopes = "user.read mail.read mail.send"
Use o comando a seguir para autenticar o usuário dentro da sessão atual do PowerShell.
# Authenticate the user Connect-MgGraph -ClientId $clientId -TenantId $tenantId -Scopes $graphScopes -UseDeviceAuthentication
Dica
Se preferir usar a autenticação interativa do navegador, omita o
-UseDeviceAuthentication
parâmetro.Abra um navegador e navegue até a URL exibida. Insira o código fornecido e entre.
Importante
Fique atento a todas as contas existentes do Microsoft 365 que são registradas no navegador ao navegar para
https://microsoft.com/devicelogin
. Use recursos do navegador, como perfis, modo convidado ou modo privado para garantir que você se autentique como a conta que pretende usar para teste.Depois de concluído, retorne à janela do PowerShell. Execute o comando a seguir para verificar o contexto autenticado.
# 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
Obter usuário
Nesta seção, você receberá o usuário autenticado.
Em sua sessão autenticada do PowerShell, execute o comando a seguir para obter o contexto atual. O contexto fornece informações para identificar o usuário autenticado.
$context = Get-MgContext
Execute o comando a seguir para obter o usuário do Microsoft Graph.
# Get the authenticated user by UPN $user = Get-MgUser -UserId $context.Account -Select 'displayName, id, mail, userPrincipalName'
Dica
Você pode adicionar a opção
-Debug
ao comando anterior para ver a solicitação e a resposta da API.Execute os comandos a seguir para gerar informações do usuário.
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
Código explicado
Considere o comando usado para obter o usuário autenticado. É um comando aparentemente simples, mas há alguns detalhes importantes a serem notados.
Acessando 'me'
O Get-MgUser
comando cria uma solicitação para a API obter usuário . Essa API está acessível de duas maneiras:
GET /me
GET /users/{user-id}
O SDK do Microsoft Graph PowerShell não dá suporte ao ponto de extremidade da GET /me
API. Para usar o GEt /users/{user-id}
ponto de extremidade, devemos fornecer um valor para o {user-id}
parâmetro. No exemplo acima, o $context.Account
valor é usado. Esse valor contém o UPN (nome de entidade de usuário) do usuário autenticado.
Solicitando propriedades específicas
A função usa o -Select
parâmetro no comando para especificar o conjunto de propriedades de que precisa. Isso adiciona o parâmetro de consulta $select à chamada de API.
Tipo de retorno fortemente tipado
A função retorna um MicrosoftGraphUser
objeto desserializado da resposta JSON da API. Como o comando usa -Select
, apenas as propriedades solicitadas terão valores no objeto retornado. Todas as outras propriedades terão valores padrão.
Caixa de entrada listar
Nesta seção, você listará mensagens na caixa de entrada de email do usuário.
Em sua sessão autenticada do PowerShell, verifique se a
$user
variável está definida.PS > $user.DisplayName Megan Bowen
Execute o comando a seguir para listar a caixa de entrada do usuário.
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
Examine a saída.
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
Código explicado
Considere o comando usado para listar a caixa de entrada do usuário
Acessando pastas de email bem conhecidas
O Get-MgUserMailFolderMessage
comando cria uma solicitação para a API de mensagens de lista , especificamente usando o GET /users/{user-id}/mailFolders/{folder-id}/messages
ponto de extremidade. Usando esse ponto de extremidade, a API só retorna mensagens na pasta de email solicitada. Nesse caso, como a caixa de entrada é uma pasta padrão e conhecida dentro da caixa de correio de um usuário, ela é acessível por meio de seu nome conhecido: -MailFolderId Inbox
. As pastas não padrão são acessadas da mesma maneira, substituindo o nome conhecido pela propriedade ID da pasta de email. Para obter detalhes sobre os nomes de pastas conhecidos disponíveis, consulte o tipo de recurso mailFolder.
Acessando uma coleção
Ao contrário do Get-MgUser
comando da seção anterior, que retorna um único objeto, esse método retorna uma coleção de mensagens. A maioria das APIs no Microsoft Graph que retornam uma coleção não retorna todos os resultados disponíveis em uma única resposta. Em vez disso, eles usam paginação para retornar uma parte dos resultados, fornecendo um método para os clientes solicitarem a próxima "página".
Tamanhos de página padrão
APIs que usam paginação implementam um tamanho de página padrão. Para mensagens, o valor padrão é 10. Os clientes podem solicitar mais (ou menos) usando o parâmetro de consulta $top . No SDK do Microsoft Graph PowerShell, isso é feito com o -Top 25
parâmetro.
Observação
O valor passado por meio -Top
é um limite superior, não um número explícito. A API retorna várias mensagens até o valor especificado.
Classificando coleções
A função usa o -OrderBy
parâmetro na solicitação para solicitar resultados classificados no momento em que a mensagem é recebida (receivedDateTime
propriedade). Ele inclui o palavra-chave para que as DESC
mensagens recebidas mais recentemente sejam listadas primeiro. Isso adiciona o parâmetro de consulta $orderby à chamada de API.
Enviar email
Nesta seção, você enviará uma mensagem de email como o usuário autenticado.
Em sua sessão autenticada do PowerShell, verifique se a
$user
variável está definida.PS > $user.DisplayName Megan Bowen
Use o comando a seguir para definir um objeto que representa o corpo da solicitação para a API enviar email .
$sendMailParams = @{ Message = @{ Subject = "Testing Microsoft Graph" Body = @{ ContentType = "text" Content = "Hello world!" } ToRecipients = @( @{ EmailAddress = @{ Address = ($user.Mail ?? $user.UserPrincipalName) } } ) } }
Use o comando a seguir para enviar a mensagem.
Send-MgUserMail -UserId $user.Id -BodyParameter $sendMailParams
Observação
Se você estiver testando com um locatário do desenvolvedor do Microsoft 365 Developer Program, o email enviado talvez não seja entregue e você poderá receber um relatório de não entrega. Se isso acontecer com você, entre em contato com o suporte por meio do Centro de administração do Microsoft 365.
Para verificar se a mensagem foi recebida, repita o
Get-MgUserMailFolderMessage
comando da etapa anterior.
Código explicado
Considere os comandos usados para enviar uma mensagem.
Enviar email
O Send-MgUserMail
comando cria uma solicitação para a API enviar email .
Criando objetos
Ao contrário das chamadas anteriores para o Microsoft Graph que só leem dados, essa chamada cria dados. Para fazer isso com o SDK, crie um objeto que representa o corpo da solicitação, defina as propriedades desejadas e passe-o BodyParameter
no parâmetro.
Opcional: adicionar seu próprio código
Nesta seção, você usará seus próprios comandos do SDK do Microsoft Graph PowerShell. Isso pode ser um snippet de código da documentação do Microsoft Graph ou do Graph Explorer ou código que você criou. Esta seção é opcional.
Escolher uma API
Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar eventos . Você pode usar um dos exemplos na documentação da API, personalizar uma solicitação de API no Graph Explorer e usar o snippet gerado ou usar o Find-MgGraphCommand
comando para localizar o comando correspondente.
Por exemplo, um dos pontos de extremidade da API para criar um evento é POST /users/{id | userPrincipalName}/events
. Você pode usá-lo para localizar o comando do PowerShell correspondente.
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…
A saída indica que o New-MgUserEvent
comando é o comando correspondente.
Configurar as permissões
Verifique a seção Permissões da documentação de referência da API escolhida para ver quais métodos de autenticação têm suporte. Algumas APIs não dão suporte à autenticação de usuário (delegado) ou contas pessoais da Microsoft, por exemplo.
Desconecte a sessão atual (Disconnect-MgGraph
) e reconecte-se com a permissão necessária no -Scopes
parâmetro.
Dica
O uso do -ForceRefresh
parâmetro com o Connect-MgGraph
comando garante que as permissões recém-configuradas sejam aplicadas.
Executar o comando
Agora que você está conectado com as permissões necessárias, execute o comando escolhido.
Parabéns!
Você concluiu o tutorial do Microsoft Graph do PowerShell. Agora que você tem um aplicativo de trabalho que chama Microsoft Graph, você pode experimentar e adicionar novos recursos.
- Saiba como usar a autenticação somente aplicativo com o SDK do Microsoft Graph PowerShell.
- Visite a visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.