M365Con 2027 – conferência online gratuita · 11–22 Jan 2027 · 120 sessions→ m365con.net

Blog · Mirko Peters

Microsoft Graph PowerShell para administradores do SharePoint: primeiros comandos

By · · Updated

Microsoft Graph PowerShell para SharePoint: instale o SDK, entre com o escopo certo, liste sites com Get-MgSite e resolva os erros 403 que os administradores encontram primeiro.

Automatically translated with AI from the original post. Read the English original

O Microsoft Graph PowerShell para SharePoint significa usar o SDK do Graph para ler e gerenciar sites pela linha de comando. Você instala um único módulo, entra com Connect-MgGraph e um escopo de permissão, e executa cmdlets como Get-MgSite. Este guia é para administradores do SharePoint que já conhecem o centro de administração do SharePoint e querem um primeiro caminho seguro para a automação com scripts. Você vai instalar o SDK, entrar com o menor escopo que funciona, listar sites e aprender a interpretar os primeiros erros que aparecem.

Pontos-chave

  • O Microsoft Graph PowerShell é um SDK que encapsula as APIs do Graph, então todo comando exige antes um login com Connect-MgGraph e os escopos de permissão corretos.
  • O Get-MgSite lista sites do SharePoint e exige, no mínimo, a permissão Sites.Read.All, que é a opção de menor privilégio documentada pela Microsoft para esse comando.
  • O Get-MgContext mostra quais escopos a sua sessão atual possui, que é a forma mais rápida de explicar um erro 403 Forbidden.
  • Find-MgGraphCommand e Find-MgGraphPermission informam qual permissão um comando exige, para que você não precise adivinhar nomes de escopos.
  • O login delegado é indicado para uma pessoa em frente ao teclado, enquanto o login somente de aplicativo, com certificado ou identidade gerenciada, é indicado para tarefas não supervisionadas.

O que é o Microsoft Graph PowerShell e por que os administradores o utilizam

O Microsoft Graph é a API única para os dados do Microsoft 365: usuários, grupos, arquivos, e-mail, Teams e sites do SharePoint. O SDK do Microsoft Graph PowerShell encapsula a API do Graph em cmdlets. Você não precisa escrever requisições web para cada endpoint. Você executa Get-MgSite e recebe objetos de site de volta.

Para um administrador do SharePoint, isso traz três benefícios práticos.

  • Uma ferramenta para vários serviços. O mesmo login funciona para sites, usuários e grupos. Um script pode listar sites e, em seguida, consultar os proprietários deles.
  • Um modelo de permissões que você consegue entender. Cada chamada exige permissões nomeadas, chamadas de escopos. Você pode ver quais escopos uma sessão possui e por que uma chamada foi recusada.
  • Um caminho para sair dos módulos antigos. As notas da entidade do Microsoft Graph PowerShell descrevem o módulo como o substituto dos módulos desativados Azure AD PowerShell e MSOnline.

O módulo comunitário PnP PowerShell é a outra escolha comum para scripts do SharePoint, e a documentação dele observa que alguns cmdlets também se comunicam com o Graph. O Graph PowerShell não substitui todas as ferramentas de administração do SharePoint. Ele cobre o que a API do Graph expõe. Algumas configurações do locatário ainda ficam no centro de administração do SharePoint ou em outros módulos. Trate o Graph como uma ferramenta do seu conjunto, e não como a única.

Passo 1: instale o SDK e entre

O guia de instalação recomenda o PowerShell 7 ou superior em todas as plataformas. O Windows PowerShell exige a versão 5.1 ou superior, o .NET Framework 4.7.2 ou superior e uma política de execução de RemoteSigned ou menos restritiva.

Siga estas etapas:

  1. Instale o módulo para a sua própria conta: Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Use -Scope AllUsers somente se você tiver direitos de administrador e precisar de uma instalação compartilhada.
  2. Verifique o resultado com Get-InstalledModule Microsoft.Graph.
  3. Saiba que o módulo principal instala mais de 47 submódulos. A página informa que você pode instalar apenas os que precisar e que o Microsoft.Graph.Authentication vem junto com eles.
  4. Atualize depois com Update-Module Microsoft.Graph. Um módulo desatualizado é uma causa listada de conflitos de versão.

Instalar em uma versão do PowerShell não o instala na outra, então execute o comando na versão que você vai usar.

Agora faça o login. A página sobre comandos de autenticação explica que o SDK oferece dois tipos de acesso: delegado e somente de aplicativo. O acesso delegado atua em nome de um usuário conectado, e suas permissões são escopos. O acesso somente de aplicativo é executado sem um usuário, com um certificado, um segredo de cliente ou uma identidade gerenciada.

Para os seus primeiros comandos, use o acesso delegado e solicite um único escopo somente leitura:

Connect-MgGraph -Scopes "Sites.Read.All"

Uma janela do navegador é aberta para o login. Para verificar o que você obteve, execute Get-MgContext | Select -ExpandProperty Scopes. A Microsoft documenta o Get-MgContext como o comando que retorna os detalhes da sessão atual, como o ID do cliente, o ID do locatário, os escopos e o tipo de autenticação. Ao terminar, execute Disconnect-MgGraph. A página informa que você permanece conectado até fazer isso, porque os tokens ficam em cache no escopo padrão CurrentUser. Adicione -ContextScope Process ao Connect-MgGraph se quiser que o login dure apenas durante a sessão atual.

Primeiros comandos para sites do SharePoint

A referência do Get-MgSite lista os principais parâmetros: -Filter, -Search, -Property (alias -Select), -Top, -Sort e -All. Os exemplos da própria página são curtos:

  • Get-MgSite lista os sites.
  • Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null" retorna apenas as coleções de sites raiz, com duas propriedades.

A partir daí, avance aos poucos:

  1. Listar com paginação. Execute Get-MgSite -All para percorrer todas as páginas de resultados. Sem o -All, você pode ver apenas a primeira página.
  2. Escolha as colunas. Adicione -Property "id,displayName,webUrl" para que a saída fique pequena e legível.
  3. Pesquise por palavra-chave. Execute Get-MgSite -Search "finance". A API de pesquisa do Graph encontra texto livre em várias propriedades de site.
  4. Obtenha um site. Execute Get-MgSite -SiteId <id>, em que o ID é o valor de id de um resultado anterior. Ele tem o formato de um nome de host, seguido de dois GUIDs, separados por vírgulas.

Cada um desses cmdlets corresponde a uma chamada REST. Get-MgSite -All lê a coleção de sites em https://graph.microsoft.com/v1.0/sites, a URL que a documentação REST mostra para listar sites, e -Filter, -Search e -Property se tornam opções de consulta nessa URL. O SDK obtém seus tokens por meio da Microsoft Authentication Library (MSAL). Se faltar um cmdlet para uma chamada que você precisa, o Invoke-MgGraphRequest pode chamar um URI diretamente. A página de solução de problemas o usa para verificar o URI por trás de um erro Bad request.

Dois limites são importantes. Primeiro, o endpoint de listagem do Graph retorna os sites na geografia padrão da organização. Para todas as geografias, a Microsoft indica a API getAllSites, que corresponde ao cmdlet Get-MgAllSite. Segundo, a API de pesquisa só pode ordenar por createdDateTime.

Quais permissões você precisa? Escopos do Microsoft Graph PowerShell e do SharePoint

As permissões do Microsoft Graph são a parte que surpreende quem está começando. Para leitura de sites, a página do cmdlet lista Sites.Read.All como a opção de menor privilégio e Sites.ReadWrite.All como a de maior privilégio. Escolha a primeira, a menos que um script precise alterar algo.

Você não precisa decorar nomes de escopos. Dois comandos auxiliares fazem a busca:

  • Find-MgGraphCommand mostra quais permissões um cmdlet ou API exige. A página de solução de problemas usa Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions como exemplo.
  • Find-MgGraphPermission encontra permissões por área ou nome, como em Find-MgGraphPermission application. A saída mostra o tipo (delegada ou de aplicativo), se o consentimento precisa ser dado por um administrador e uma descrição.

Há um ponto de divergência na documentação. A página REST para listar sites mostra apenas permissões de aplicativo para essa chamada e indica que o acesso delegado não é suportado. A página do cmdlet Get-MgSite lista as duas. Teste sua própria chamada em um locatário que não seja de produção e leia o texto do erro se ela falhar. Não presuma que a página do cmdlet está correta para todas as chamadas.

Para tarefas não assistidas, você precisa de acesso somente de aplicativo. Isso significa um registro de aplicativo no Microsoft Entra, permissões de aplicativo (também chamadas de permissões de API) e consentimento de administrador. A página de solução de problemas informa que permissões de aplicativo exigem consentimento de administrador. Use um certificado ou uma identidade gerenciada, não uma senha digitada.

Exemplo: um inventário de sites inativos em cinco comandos

Os números deste exemplo são fictícios.

Um administrador quer uma primeira lista de sites que ninguém alterou há um ano.

  1. Connect-MgGraph -Scopes "Sites.Read.All"
  2. $sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"
  3. $sites.Count retorna 480 neste exemplo.
  4. $old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }
  5. $old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation

Suponha que o arquivo tenha 60 linhas. São 60 de 480, ou 12,5 por cento, uma lista curta para revisar com os proprietários dos sites. O administrador tem apenas acesso de leitura e não alterou nada. A data da última modificação de um site não prova que ninguém o usa, por isso a lista é um ponto de partida para fazer perguntas, não uma lista de exclusão.

Erros comuns

  • Conectar sem um escopo. Um login sem o escopo correto leva a erros 403. Execute Get-MgContext e compare os escopos com o que o cmdlet precisa.
  • Pedir escopos de gravação para uma tarefa de leitura. Sites.ReadWrite.All é mais do que um relatório precisa. Comece com Sites.Read.All.
  • Esquecer o -All. Sem ele, uma lista pode parecer completa quando é apenas a primeira página.
  • Confundir as versões do módulo. A Microsoft recomenda o módulo v1.0 para scripts. O módulo beta está em prévia e pode mudar sem aviso.
  • Pular a atualização. Uma versão antiga do Microsoft.Graph é uma causa conhecida de conflitos de versão. Execute Update-Module Microsoft.Graph antes de investigar outras causas.
  • Continuar conectado em um computador compartilhado. Os tokens ficam em cache. Execute Disconnect-MgGraph quando terminar.

Como o software pode ajudar

A maioria das necessidades iniciais é atendida por ferramentas que você já possui. O Microsoft Graph PowerShell SDK cuida das leituras e exportações. O centro de administração do SharePoint mostra listas e configurações de sites sem código. O Excel ou o Power BI transforma um CSV em um relatório que os proprietários dos sites conseguem ler. Para execuções agendadas, o Azure Automation pode executar um script com uma identidade gerenciada.

Procure lacunas somente após o primeiro mês. Se você continuar refazendo o mesmo inventário manualmente, um script salvo com uma pasta de saída fixa e um lembrete mensal geralmente é suficiente.

Próximo passo

Instale o SDK, execute Connect-MgGraph -Scopes "Sites.Read.All" e exporte a saída de Get-MgSite -All para um CSV hoje. Depois, use Find-MgGraphCommand no seu próximo cmdlet para descobrir a permissão necessária antes de executar tarefas do SharePoint com o Microsoft Graph PowerShell em produção.

Seguir o podcastSpotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS