Como usar a Microsoft Graph API com o Windows PowerShell para monitorar e gerenciar clientes do Microsoft 365

A Microsoft Graph API é um endpoint unificado que dá aos administradores acesso programático a vários serviços do Microsoft 365, como Intune, Microsoft Entra (antigo Azure AD), Exchange Online, Teams e muito mais, usando o Windows PowerShell.

Os casos de uso são muitos, principalmente em ambientes corporativos. A Microsoft Graph API serve para:

• Monitorar conformidade e integridade de dispositivos
• Acompanhar uso e atribuição de licenças
• Automatizar o gerenciamento de políticas e grupos
• Criar fluxos de alerta e correção
• Gerar relatórios entre tenants para painéis de MSP

Pré-requisitos:

• É necessário ter um tenant do Microsoft 365 com acesso de administrador global ou delegado.
• É preciso registrar o Microsoft Graph no Microsoft Entra (antigo Azure AD).
• Algumas ações podem exigir licenças do Intune e do Microsoft Entra Premium.
• Você vai precisar de uma baseline de GPO para proteger os tokens de autenticação e garantir que a execução dos scripts seja segura.

Para uma visão geral rápida, assista ao nosso guia em vídeo: Como usar a Microsoft Graph API com o Windows PowerShell para monitorar e gerenciar clientes do Microsoft 365.

Como instalar o Microsoft Graph PowerShell SDK

Pré-requisitos:

• O recomendado é usar o Windows PowerShell 7 ou superior. O Windows PowerShell 5.1 é o requisito mínimo. (Verifique a versão do seu PowerShell )
• É preciso ter o .NET Framework 4.7.2 ou superior instalado.
• O PowerShellGet deve estar atualizado para a versão mais recente. Para isso, digite Install-Module PowerShellGet no Windows PowerShell e pressione Enter.
• A política de execução precisa estar definida como remote signed ou menos restritiva. Para conferir se a política está correta, digite Get-ExecutionPolicy no Windows PowerShell e pressione Enter. Para mudar a política de execução para remote signed, digite Set-ExecutionPolicy -ExecutionPolicy RemoteSigned e pressione Enter.

Passos:

1. Abra o Menu Iniciar e procure por Windows PowerShell.
2. Clique com o botão direito em Windows PowerShell > Executar como administrador.
3. Digite Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force e pressione Enter.

Observação: essa mudança vale apenas para o perfil de usuário atual. Para instalar o Microsoft Graph PowerShell SDK em todos os perfis, troque o -Scope para AllUsers.

4. Confirme a instalação quando solicitado.

Como se conectar ao Microsoft Graph PowerShell SDK

1. Digite Connect-MgGraph -Scopes "User.Read.All",”DeviceManagementManagedDevices.Read.All”,”Directory.Read.All” no Windows PowerShell e pressione Enter para conectar.

Observação: isso dá acesso ao Graph inteiro. Dá para ajustar as permissões conforme a necessidade, editando o que vem depois de -Scopes. Para ver todas as permissões disponíveis, digite Find-MgGraphCommand -command Get-MgGroup.

2. Se já estiver conectado, siga para o próximo passo. Se não, siga as instruções na tela para fazer login.
3. Também dá para usar Get-MgContext para obter detalhes específicos, como ID do cliente, ID do tenant, escopos consentidos e mais.

Observação: use -TenantID para acesso multi-tenant e -ClientID para aplicativos registrados.

Como obter informações de dispositivos e status de conformidade

Para listar todos os dispositivos gerenciados pelo Intune, digite este comando e pressione Enter:

Get-MgDeviceManagementManagedDevice |
Select DisplayName, ComplianceState, OperatingSystem

Para encontrar dispositivos não conformes nessa lista, digite este comando e pressione Enter:

Get-MgDeviceManagementManagedDevice |
Where-Object {$_.ComplianceState -ne "compliant"}

Também é possível localizar dispositivos específicos pelo nome:

Get-MgDeviceManagementManagedDevice -ManagedDeviceId <GUID>

Troque <GUID> pelo ID do dispositivo que está procurando.

Como monitorar atividade de usuários e licenciamento

Para listar todos os usuários com os respectivos detalhes de licença, digite este comando e pressione Enter:

Get-MgUser | Select-Object DisplayName, UserPrincipalName, AssignedLicenses

Para encontrar usuários sem licença, digite este comando e pressione Enter:

Get-MgUser | Where-Object { !$_.AssignedLicenses }
Obter atividade de login (requer AuditLog.Read.All):
Get-MgAuditLogSignIn -Top 50 | Select UserDisplayName, UserPrincipalName, Status, AppDisplayName

Como automatizar a correção e a aplicação de políticas

Se um dispositivo for perdido ou comprometido, apague os dados dele pelo Microsoft Graph digitando este comando e pressionando Enter:

Invoke-MgDeviceManagementManagedDeviceWipe -ManagedDeviceId <GUID>

Substitua <GUID> pelo ID do dispositivo perdido ou comprometido.

Para bloquear um dispositivo remotamente:

Invoke-MgDeviceManagementManagedDeviceRemoteLock -ManagedDeviceId <GUID>

Substitua <GUID> pelo ID do dispositivo perdido ou comprometido.

Para atribuir uma política de conformidade, digite este comando e pressione Enter:

New-MgDeviceManagementCompliancePolicyAssignment -CompliancePolicyId <PolicyID> -Target @{ “@odata.type” = “#microsoft.graph.groupAssignmentTarget”; “groupId” = “<EntraGroupId>” }

Troque <PolicyID> pelo ID da política que quer atribuir. Troque <EntraGroupId> pelo grupo que vai receber a política.

Esses comandos ajudam bastante na hora de configurar correções automáticas em ambientes diferentes. Também dá para dispará-los automaticamente quando o sistema recebe um alerta da ferramenta de gerenciamento de endpoints.

Como validar políticas no endpoint (Editor do Registro, Prompt de Comando)

Para confirmar se as políticas enviadas pelo Microsoft Graph foram aplicadas, verifique o Editor do Registro do Windows.

Por exemplo, acesse HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PolicyManager\current\device\ no Editor do Registro e veja se as políticas foram aplicadas (Defender, política de criptografia etc.).

Também dá para usar o Prompt de Comando para registrar o dispositivo em um MDM e acompanhar o status de perto.

1. Abra o Prompt de Comando como administrador.
2. Digite isto e pressione Enter: start ms-device-enrollment:?mode=mdm

Para verificar o status de ingresso/registro, digite: dsregcmd /status

Como proteger o uso de tokens com Políticas de Grupo Locais e controles no endpoint

Use Políticas de Grupo Locais para proteger os tokens de autenticação do Microsoft Graph e a automação em PowerShell nos dispositivos gerenciados. Siga estes passos:

1. Abra o Editor de Política de Grupo Local.
2. Vá para Configuração do Computador > Configurações do Windows > Configurações de Segurança > Políticas Locais > Opções de Segurança
3. Localize Não permitir o armazenamento de senhas e credenciais para autenticação de rede e dê dois cliques.
4. Defina como Ativado.
5. Clique em Aplicar > OK.
6. Vá para Configuração do Computador > Modelos Administrativos > Componentes do Windows > Windows PowerShell.
7. Localize Ativar Execução de Script e dê dois cliques.
8. Defina como Ativado.
9. Abra o menu suspenso e selecione Permitir apenas scripts assinados.
10. Clique em Aplicar > OK.

Outros pontos de atenção ao usar a Microsoft Graph API

• Use o Graph Explorer para testar a API on-line, sem instalar nada nos dispositivos.
• Aplique permissões de aplicativo para tarefas em segundo plano e scripts multi-tenant.
• Adote limitação de taxa e lógica de repetição nos scripts de produção.
• Use políticas de acesso condicional do Microsoft Entra ID para restringir o uso do Graph em dispositivos não gerenciados.

Solução de problemas da Microsoft Graph API

Serviços NinjaOne

NinjaOne complementa a Microsoft Graph API de várias formas:

• Automatiza scripts do Microsoft Graph em todos os tenants dos clientes com uma ferramenta remota de PowerShell
• Configura alertas para que os administradores saibam quando um dispositivo deixa de estar em conformidade e aciona correções via Graph
• Marca dispositivos com campos personalizados a partir de metadados do Microsoft Graph (estado de conformidade, nível de risco etc.)
• Agenda tarefas de relatório com informações do Microsoft Graph e centraliza a visibilidade por tenant para MSPs.

Monitore os dispositivos gerenciados com a Microsoft Graph API

A Microsoft Graph API é uma ferramenta poderosa: dá aos administradores controle centralizado e automatizado das contas do Microsoft 365 da organização por meio do Windows PowerShell. Depois de instalar e conectar pelo PowerShell, use-a para monitorar usuários e a conformidade dos dispositivos, além de automatizar ações e atribuições de políticas.

Valide essas atribuições verificando o Editor do Registro do Windows e usando o Prompt de Comando. E vá além nos seus fluxos de trabalho com os recursos de automação e visibilidade do NinjaOne.

Artigos relacionados:

• Como aprimorar o NinjaOne Ticketing com a integração SMTP do Microsoft 365
• Integração de ambientes locais e na nuvem com o Hybrid Azure AD Join
• Guia completo: tudo sobre monitoramento de sistemas de TI
• Ferramentas de monitoramento na nuvem: as 5 melhores soluções em 2026
• Monitoramento de endpoints explicado com um exemplo