Ligar ao Microsoft 365 com o Microsoft Graph PowerShell

  • Artigo

Este artigo aplica-se tanto a Microsoft 365 Enterprise como a Office 365 Enterprise.

O Microsoft Graph PowerShell permite-lhe gerir as suas definições do Microsoft 365 a partir da linha de comandos. Este artigo mostra-lhe como instalar o software necessário e, em seguida, ligar à sua organização do Microsoft 365 com o SDK do PowerShell do Microsoft Graph.

Atualmente, o módulo do PowerShell do Azure Active Directory para Graph não substitui completamente a funcionalidade do módulo Microsoft Azure Active Directory para Windows PowerShell para gestão de proxy de aplicações, utilizador e administração de contactos. Em alguns casos, tem de utilizar ambas as versões. Pode instalar ambas as versões com segurança no mesmo computador.

O que precisa de saber antes de começar?

Nota

O módulo do PowerShell do Azure Active Directory (AzureAD) está a ser preterido e substituído pelo SDK do PowerShell do Microsoft Graph. Pode utilizar o SDK do PowerShell do Microsoft Graph para aceder a todas as APIs do Microsoft Graph. Para obter mais informações, veja Introdução ao SDK do PowerShell do Microsoft Graph.

Veja também Instalar o SDK do PowerShell do Microsoft Graph e Atualizar do Azure AD PowerShell para o Microsoft Graph PowerShell para obter informações sobre como instalar e atualizar para o Microsoft Graph PowerShell, respetivamente.

Pré-requisitos

O PowerShell 7 e posterior é a versão recomendada do PowerShell para utilização com o SDK do PowerShell do Microsoft Graph em todas as plataformas. Não existem outros pré-requisitos para utilizar o SDK com o PowerShell 7 ou posterior.

Os seguintes pré-requisitos são necessários para utilizar o SDK do PowerShell do Microsoft Graph com Windows PowerShell.

  • Atualizar para o PowerShell 5.1 ou posterior
  • Instalar .NET Framework 4.7.2 ou posterior
  • Atualizar o PowerShellGet para a versão mais recente com Install-Module PowerShellGet

A política de execução do script do PowerShell tem de ser definida como assinada remotamente ou menos restritiva. Utilize Get-ExecutionPolicy para determinar a política de execução atual. Para obter mais informações, veja about_Execution_Policies. Para definir a política de execução, execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Sistema operativo

Tem de utilizar uma versão de 64 bits do Windows. Pode utilizar as seguintes versões do Windows:

  • Windows 11, Windows 10, Windows 8.1, Windows 8 ou Windows 7 Service Pack 1 (SP1)

  • Windows Server 2019, Windows Server 2016, Windows Server 2012 R2, Windows Server 2012 ou Windows Server 2008 R2 SP1

Nota

Para Windows 8.1, Windows 8, Windows 7 Service Pack 1 (SP1), Windows Server 2012 R2, Windows Server 2012 e Windows Server 2008 R2 SP1, transfira e instale o Windows Management Framework 5.1.

Para utilizar o PowerShell do Microsoft Graph, tem de utilizar, pelo menos, a versão 5.1 do PowerShell.

Nota

Estes procedimentos destinam-se a utilizadores que são membros de uma função de administrador do Microsoft 365. Para obter mais informações, consulte Atribuir funções de administrador.

Ligar com o PowerShell do Microsoft Graph

Nesta secção, irá aprender a ligar à sua organização do Microsoft 365 com o SDK do PowerShell do Microsoft Graph. Pode visitar Instalar o SDK do PowerShell do Microsoft Graph para obter mais orientações.

Passo 1: Instalar o software necessário

O SDK do PowerShell do Microsoft Graph é publicado no Galeria do PowerShell.

Estes passos são necessários apenas uma vez no seu computador. No entanto, provavelmente terá de atualizar o software periodicamente.

Instalar o SDK do PowerShell e o módulo beta do Microsoft Graph

O SDK do PowerShell do Microsoft Graph vem em dois módulos, Microsoft.Graph e Microsoft.Graph.Beta, que irá instalar separadamente. Estes módulos chamam os pontos finais beta do Microsoft Graph v1.0 e do Microsoft Graph, respetivamente. Pode instalar os dois módulos na mesma versão do PowerShell.

  1. Abra uma janela da Linha de Comandos do Windows PowerShell. Consoante as permissões da sua conta com sessão iniciada, poderá ter de abrir a janela do PowerShell no modo de Administrador.

  2. Para instalar o módulo v1 do SDK no PowerShell Core ou Windows PowerShell, execute o seguinte comando:

    Install-Module Microsoft.Graph -Scope CurrentUser

  3. Execute este comando para instalar o módulo beta:

    Install-Module Microsoft.Graph.Beta

Depois de concluída a instalação, pode verificar a versão instalada com o seguinte comando:

Get-InstalledModule Microsoft.Graph

Passo 2: Ligar à sua subscrição do Microsoft 365

O SDK do PowerShell suporta dois tipos de autenticação: acesso delegado e acesso apenas à aplicação. Neste guia, irá utilizar o acesso delegado para iniciar sessão como utilizador, conceder consentimento ao SDK para agir em seu nome e chamar o Microsoft Graph.

Para obter detalhes sobre como utilizar o acesso apenas à aplicação para cenários autónomos, veja Utilizar a autenticação apenas de aplicações com o SDK do PowerShell do Microsoft Graph.

Determinar os âmbitos de permissão necessários

Cada API no Microsoft Graph está protegida por um ou mais âmbitos de permissão. O utilizador que iniciar sessão tem de consentir um dos âmbitos necessários para as APIs que planeia utilizar. Neste exemplo, vamos utilizar as seguintes APIs.

  • Liste os utilizadores para localizar o ID de utilizador do utilizador com sessão iniciada.
  • List joinedTeams para obter o Teams do qual o utilizador é membro.
  • Listar canais para obter os canais numa Equipa.
  • Envie uma mensagem para enviar uma mensagem para um canal da Equipa.

O âmbito de permissão User.Read.All ativa as duas primeiras chamadas e o âmbito Group.ReadWrite.All ativa o resto. Estas permissões requerem uma conta de administrador.

Para obter mais informações sobre como determinar quais os âmbitos de permissão de que irá precisar, veja Using Find-MgGraphCommand (Utilizar Find-MgGraphCommand).

Para ligar à sua Organização do Microsoft 365, execute o seguinte comando:

Connect-MgGraph -Scopes "User.Read.All","Group.ReadWrite.All"

O comando pede-lhe para aceder a uma página Web para iniciar sessão com as suas credenciais. Depois de o fazer, o comando indica êxito com uma mensagem Bem-vindo ao Microsoft Graph! . Só tem de iniciar sessão uma vez por sessão.

Sugestão

Pode adicionar permissões de forma accreativa ao repetir o comando Connect-MgGraph com os novos âmbitos de permissão.

Consulte também