Criar scripts do PowerShell com o Microsoft Graph

Artigo
Developer (Iniciante)
21 minutos para concluir

Este tutorial ensina-o a criar um script do PowerShell que utiliza a Microsoft Graph API para aceder a dados em nome de um utilizador.

Observação

Para saber como utilizar o Microsoft Graph para aceder a dados através da autenticação apenas de aplicações, veja este tutorial de autenticação apenas de aplicações.

Neste tutorial, você vai:

Dica

Como alternativa a seguir este tutorial, pode transferir o código concluído através da ferramenta de início rápido , que automatiza o registo e a configuração de aplicações. O código transferido funciona sem quaisquer modificações necessárias.

Também pode transferir ou clonar o repositório do GitHub e seguir as instruções no README para registar uma aplicação e configurar o projeto.

Pré-requisitos

Antes de iniciar este tutorial, deverá ter o PowerShell instalado no seu computador de desenvolvimento. O PowerShell 5.1 é o requisito mínimo, mas recomenda-se o PowerShell 7.

Também deve ter uma conta escolar ou profissional da Microsoft com uma caixa de correio do Exchange Online. Se não tiver um inquilino do Microsoft 365, poderá qualificar-se para um através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.

Observação

Este tutorial foi escrito com o PowerShell 7.2.2 e o Microsoft Graph PowerShell SDK versão 1.9.5. Os passos neste guia podem funcionar com outras versões, mas isso não foi testado.

Registrar o aplicativo no portal

20 minutos restantes

Neste exercício, irá registar uma nova aplicação no Azure Active Directory para ativar a autenticação de utilizadores. Pode registar uma aplicação através do centro de administração do Microsoft Entra ou através do SDK do PowerShell do Microsoft Graph.

Registar aplicação para autenticação de utilizador

Nesta secção, irá registar uma aplicação que suporta a autenticação de utilizador através do fluxo de código do dispositivo.

Observação

O registo de uma aplicação para autenticação de utilizador para o SDK do PowerShell do Microsoft Graph é opcional. O SDK tem o seu próprio registo de aplicação e o ID de cliente correspondente. No entanto, a utilização do seu próprio ID de aplicação permite um maior controlo sobre os âmbitos de permissão para um script específico do PowerShell.

Centro de administração do Microsoft Entra
PowerShell

Abra um browser e navegue para o centro de administração do Microsoft Entra e inicie sessão com uma conta de Administrador global.
Selecione Microsoft Entra ID no painel de navegação esquerdo, expanda Identidade, expanda Aplicações e, em seguida, selecione Registos de aplicações.
Selecione Novo registro. Introduza um nome para a sua aplicação, por exemplo, Graph User Auth Tutorial.

Defina Tipos de conta suportados conforme pretendido. As opções são:

Opção	Quem pode iniciar sessão?
Contas apenas neste diretório organizacional	Apenas utilizadores na sua organização do Microsoft 365
Contas em qualquer diretório organizacional	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais)
Contas em qualquer diretório organizacional... e contas Microsoft pessoais	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais) e contas Microsoft pessoais

Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Descrição Geral da aplicação, copie o valor do ID da Aplicação (cliente) e guarde-o, irá precisar dele no próximo passo. Se escolheu Contas neste diretório organizacional apenas para Tipos de conta suportados, copie também o ID do Diretório (inquilino) e guarde-o.
Selecione Autenticação em Gerenciar. Localize a secção Definições avançadas e altere o botão de alternar Permitir fluxos de cliente públicos para Sim e, em seguida, selecione Guardar.

Para utilizar o PowerShell, precisará do SDK do PowerShell do Microsoft Graph. Se não o tiver, veja Instalar o SDK do PowerShell do Microsoft Graph para obter instruções de instalação.

Importante

O script do PowerShell requer uma conta escolar/profissional com o Administrador da aplicação, o administrador da aplicação na cloud ou a função de Administrador global. Se a sua conta tiver a função de Programador de aplicações, pode registar-se no centro de administração do Microsoft Entra.

Crie um novo ficheiro com o nomeRegisterAppForUserAuth.ps1 e adicione o seguinte código.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Salve o arquivo.
Abra o PowerShell e altere o diretório atual para a localização de RegisterAppForUserAuth.ps1.

Execute o seguinte comando, substituindo <audience-value> pelo valor pretendido (veja a tabela abaixo).

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth Tutorial" -SignInAudience <audience-value>

Valor SignInAudience	Quem pode iniciar sessão?
`AzureADMyOrg`	Apenas utilizadores na sua organização do Microsoft 365
`AzureADMultipleOrgs`	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais)
`AzureADandPersonalMicrosoftAccount`	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais) e contas Microsoft pessoais
`PersonalMicrosoftAccount`	Apenas contas Microsoft pessoais

Siga o pedido para abrir https://microsoft.com/devicelogin num browser, introduza o código fornecido e conclua o processo de autenticação.
Copie os valores do ID de Cliente e do inquilino de Autenticação a partir da saída do script. Irá precisar destes valores no próximo passo.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Observação

Repare que não configurou quaisquer permissões do Microsoft Graph no registo de aplicações. Isto deve-se ao facto de o exemplo utilizar o consentimento dinâmico para pedir permissões específicas para a autenticação do utilizador.

Adicionar autenticação de utilizador

17 minutos restantes

Nesta secção, irá autenticar uma sessão do PowerShell como utilizador do Microsoft Graph. Isto é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph.

O SDK do PowerShell do Microsoft Graph fornece dois métodos de autenticação para a autenticação do utilizador: o browser interativo e a autenticação de código do dispositivo. A autenticação interativa do browser utiliza o browser predefinido de um dispositivo para permitir que o utilizador inicie sessão. A autenticação de código do dispositivo permite a autenticação em ambientes que não têm um browser predefinido. Neste exercício, irá utilizar a autenticação de código do dispositivo.

Importante

Se ainda não tiver o SDK do PowerShell do Microsoft Graph instalado, instale-o agora antes de continuar.

Autenticar o usuário

Abra o PowerShell e utilize o seguinte comando para definir a $clientID variável de sessão, substituindo <your-client-id> pelo ID de cliente do registo da aplicação.
```
$clientId = <your-client-id>
```
Defina a variável de $tenantId sessão. Se escolheu a opção para permitir que apenas os utilizadores na sua organização iniciem sessão ao registar a sua aplicação, substitua <tenant-id> pelo ID de inquilino da sua organização. Caso contrário, substitua por common.
```
$tenantId = <tenant-id>
```

Defina a variável de $graphScopes sessão.

$graphScopes = "user.read mail.read mail.send"

Utilize o seguinte comando para autenticar o utilizador dentro da sessão atual do PowerShell.
```
# Authenticate the user
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -Scopes $graphScopes -UseDeviceAuthentication
```
Dica

Se preferir utilizar a autenticação interativa do browser, omita o -UseDeviceAuthentication parâmetro .
Abra um browser e navegue para o URL apresentado. Introduza o código fornecido e inicie sessão.

Importante

Tenha em atenção todas as contas existentes do Microsoft 365 com sessão iniciada no browser ao navegar para https://microsoft.com/devicelogino . Utilize funcionalidades do browser, como perfis, modo de convidado ou modo privado para garantir que se autentica como a conta que pretende utilizar para testes.

Depois de concluído, regresse à janela do PowerShell. Execute o seguinte comando 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

12 minutos restantes

Nesta secção, irá obter o utilizador autenticado.

Na sua sessão autenticada do PowerShell, execute o seguinte comando para obter o contexto atual. O contexto fornece informações para identificar o utilizador autenticado.
```
$context = Get-MgContext
```
Execute o seguinte comando para obter o utilizador do Microsoft Graph.
```
# Get the authenticated user by UPN
$user = Get-MgUser -UserId $context.Account -Select 'displayName, id, mail, userPrincipalName'
```
Dica

Pode adicionar o -Debug comutador ao comando anterior para ver o pedido e a resposta da API.

Execute os seguintes comandos para exportar as informações do utilizador.

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 utilizado para obter o utilizador autenticado. É um comando aparentemente simples, mas há alguns detalhes importantes a notar.

Aceder a 'eu'

O Get-MgUser comando cria um pedido para a API Obter utilizador . Esta API está acessível de duas formas:

GET /me
GET /users/{user-id}

O SDK do PowerShell do Microsoft Graph não suporta o ponto final da GET /me API. Para utilizar o GEt /users/{user-id} ponto final, temos de fornecer um valor para o {user-id} parâmetro . No exemplo acima, o $context.Account valor é utilizado. Este valor contém o nome principal de utilizador (UPN) do utilizador autenticado.

Pedir propriedades específicas

A função utiliza o -Select parâmetro no comando para especificar o conjunto de propriedades de que precisa. Esta ação adiciona o parâmetro de consulta $select à chamada à API.

Tipo de retorno fortemente escrito

A função devolve um MicrosoftGraphUser objeto serializado da resposta JSON da API. Uma vez que o comando utiliza -Select, apenas as propriedades pedidas terão valores no objeto devolvido. Todas as outras propriedades terão valores predefinidos.

Listar caixa de entrada

10 minutos restantes

Nesta secção, irá listar mensagens na caixa de entrada do e-mail do utilizador.

Na sua sessão autenticada do PowerShell, verifique se a $user variável está definida.
```
PS > $user.DisplayName
Megan Bowen
```

Execute o seguinte comando para listar a caixa de entrada do utilizador.

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

Reveja o resultado.

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 utilizado para listar a caixa de entrada do utilizador

Aceder a pastas de correio conhecidas

O Get-MgUserMailFolderMessage comando cria um pedido para a API Listar mensagens , especificamente através do GET /users/{user-id}/mailFolders/{folder-id}/messages ponto final. Com esse ponto final, a API só devolve mensagens na pasta de correio pedida. Neste caso, uma vez que a caixa de entrada é uma pasta predefinida e conhecida dentro da caixa de correio de um utilizador, é acessível através do nome conhecido: -MailFolderId Inbox. As pastas não predefinidas são acedidas da mesma forma ao substituir o nome conhecido pela propriedade ID da pasta de correio. Para obter detalhes sobre os nomes de pastas conhecidos disponíveis, consulte mailFolder resource type (Tipo de recurso mailFolder).

Aceder a uma coleção

Ao contrário do Get-MgUser comando da secção anterior, que devolve um único objeto, este método devolve uma coleção de mensagens. A maioria das APIs no Microsoft Graph que devolvem uma coleção não devolvem todos os resultados disponíveis numa única resposta. Em vez disso, utilizam a paginação para devolver uma parte dos resultados, ao mesmo tempo que fornecem um método para os clientes solicitarem a "página" seguinte.

Tamanhos de página predefinidos

As APIs que utilizam a paginação implementam um tamanho de página predefinido. Para mensagens, o valor predefinido é 10. Os clientes podem pedir mais (ou menos) através do parâmetro de consulta $top . No SDK do PowerShell do Microsoft Graph, isto é feito com o -Top 25 parâmetro .

Observação

O valor transmitido através -Top de é um limite superior, não um número explícito. A API devolve um número de mensagens até ao valor especificado.

Classificando coleções

A função utiliza o -OrderBy parâmetro no pedido para pedir resultados ordenados quando a mensagem é recebida (receivedDateTime propriedade). Inclui a palavra-chave para que as DESC mensagens recebidas mais recentemente sejam listadas primeiro. Esta ação adiciona o parâmetro de consulta $orderby à chamada à API.

Enviar email

8 minutos restantes

Nesta secção, irá enviar uma mensagem de e-mail como o utilizador autenticado.

Na sua sessão autenticada do PowerShell, verifique se a $user variável está definida.
```
PS > $user.DisplayName
Megan Bowen
```

Utilize o seguinte comando para definir um objeto que representa o corpo do pedido para a API enviar correio .

$sendMailParams = @{
    Message = @{
        Subject = "Testing Microsoft Graph"
        Body = @{
            ContentType = "text"
            Content = "Hello world!"
        }
        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = ($user.Mail ?? $user.UserPrincipalName)
                }
            }
        )
    }
}

Utilize o seguinte comando para enviar a mensagem.
```
Send-MgUserMail -UserId $user.Id -BodyParameter $sendMailParams
```
Observação

Se estiver a testar com um inquilino de programador do Programa para Programadores do Microsoft 365, o e-mail que enviar poderá não ser entregue e poderá receber um relatório de entrega sem fins lucrativos. Se isto lhe acontecer, contacte o suporte através do centro de administração do Microsoft 365.
Para verificar se a mensagem foi recebida, repita o Get-MgUserMailFolderMessage comando do passo anterior.

Código explicado

Considere os comandos utilizados para enviar uma mensagem.

Enviar correio

O Send-MgUserMail comando cria um pedido para a API Enviar correio .

Criar objetos

Ao contrário das chamadas anteriores para o Microsoft Graph que só leem dados, esta chamada cria dados. Para o fazer com o SDK, crie um objeto que represente o corpo do pedido, defina as propriedades pretendidas e, em seguida, transmita-o no BodyParameter parâmetro .

Opcional: adicionar o seu próprio código

5 minutos restantes

Nesta secção, irá utilizar os seus próprios comandos do SDK do PowerShell do Microsoft Graph. Pode ser um fragmento de código da documentação do Microsoft Graph ou do Graph Explorer ou código que criou. Esta secção é opcional.

Escolher uma API

Localize uma API no Microsoft Graph que gostaria de experimentar. Por exemplo, a API Criar evento . Pode utilizar um dos exemplos na documentação da API, personalizar um pedido de API no Graph Explorer e utilizar o fragmento gerado ou utilizar o Find-MgGraphCommand comando para localizar o comando correspondente.

Por exemplo, um dos pontos finais da API para criar um evento é POST /users/{id | userPrincipalName}/events. Pode utilizá-lo para encontrar 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…

O resultado indica que o New-MgUserEvent comando é o comando correspondente.

Configurar as permissões

Verifique a secção Permissões da documentação de referência da API escolhida para ver que métodos de autenticação são suportados. Algumas APIs não suportam a autenticação de utilizador (delegada) nem contas Microsoft pessoais, por exemplo.

Desligue a sessão atual (Disconnect-MgGraph) e volte a ligar com a permissão necessária no -Scopes parâmetro .

Dica

A utilização do -ForceRefresh parâmetro com o Connect-MgGraph comando garante que as permissões recentemente configuradas são aplicadas.

Executar o comando

Agora que está ligado às permissões necessárias, execute o comando escolhido.

Compartilhar via

Criar scripts do PowerShell com o Microsoft Graph

Pré-requisitos

Registrar o aplicativo no portal

Registar aplicação para autenticação de utilizador

Adicionar autenticação de utilizador

Autenticar o usuário

Obter usuário

Código explicado

Aceder a 'eu'

Pedir propriedades específicas

Tipo de retorno fortemente escrito

Listar caixa de entrada

Código explicado

Aceder a pastas de correio conhecidas

Aceder a uma coleção

Tamanhos de página predefinidos

Classificando coleções

Enviar email

Código explicado

Enviar correio

Criar objetos

Opcional: adicionar o seu próprio código

Escolher uma API

Configurar as permissões

Executar o comando

Parabéns!