Microsoft Graph PowerShell per gli amministratori di SharePoint: i primi comandi
By Mirko Peters · · Updated
Microsoft Graph PowerShell per SharePoint: installa l'SDK, accedi con l'ambito corretto, elenca i siti con Get-MgSite e risolvi gli errori 403 che gli amministratori incontrano per primi.
Automatically translated with AI from the original post. Read the English original
Microsoft Graph PowerShell per SharePoint significa usare l'SDK di Graph per leggere e gestire i siti da riga di comando. Installi un solo modulo, accedi con Connect-MgGraph e un ambito di autorizzazione, ed esegui cmdlet come Get-MgSite. Questa guida è rivolta agli amministratori di SharePoint che già conoscono l'interfaccia di amministrazione di SharePoint e vogliono un primo percorso sicuro verso lo scripting. Installerai l'SDK, accederai con l'ambito minimo funzionante, elencherai i siti e imparerai a leggere gli errori che compaiono per primi.
Punti chiave
- Microsoft Graph PowerShell è un SDK che incapsula le API di Graph, quindi ogni comando richiede prima un accesso con Connect-MgGraph e gli ambiti di autorizzazione corretti.
- Get-MgSite elenca i siti di SharePoint e richiede almeno l'autorizzazione Sites.Read.All, che è l'opzione con privilegi minimi documentata da Microsoft per questo comando.
- Get-MgContext mostra quali ambiti possiede la sessione attuale, ed è il modo più rapido per spiegare un errore 403 Forbidden.
- Find-MgGraphCommand e Find-MgGraphPermission indicano quale autorizzazione richiede un comando, così non devi indovinare i nomi degli ambiti.
- L'accesso delegato è adatto a una persona davanti alla tastiera, mentre l'accesso solo applicativo con certificato o identità gestita è adatto ai processi senza intervento umano.
Che cos'è Microsoft Graph PowerShell e perché lo usano gli amministratori
Microsoft Graph è l'API unica per i dati di Microsoft 365: utenti, gruppi, file, posta, Teams e siti di SharePoint. L'SDK PowerShell di Microsoft Graph incapsula l'API di Graph in cmdlet. Non scrivi richieste web verso ogni endpoint: esegui Get-MgSite e ottieni indietro oggetti sito.
Per un amministratore di SharePoint, questo offre tre vantaggi pratici.
- Uno strumento per più servizi. Lo stesso accesso funziona per siti, utenti e gruppi. Uno script può elencare i siti e poi cercarne i proprietari.
- Un modello di autorizzazioni leggibile. Ogni chiamata richiede autorizzazioni precise, chiamate ambiti. Puoi vedere quali ambiti possiede una sessione e perché una chiamata è stata rifiutata.
- Un percorso lontano dai moduli obsoleti. Le note sull'entità Microsoft Graph PowerShell lo descrivono come il sostituto dei moduli Azure AD PowerShell e MSOnline, ormai ritirati.
Il modulo PnP PowerShell della community è l'altra scelta comune per lo scripting di SharePoint, e la sua documentazione segnala che alcuni cmdlet comunicano anche con Graph. Graph PowerShell non sostituisce ogni strumento di amministrazione di SharePoint: copre ciò che espone l'API di Graph. Alcune impostazioni del tenant si trovano ancora nell'interfaccia di amministrazione di SharePoint o in altri moduli. Considera Graph come uno strumento del tuo set, non come l'unico.
Passaggio 1: installa l'SDK e accedi
La guida all'installazione consiglia PowerShell 7 o versioni successive su tutte le piattaforme. Windows PowerShell richiede la versione 5.1 o successiva, .NET Framework 4.7.2 o successivo e un criterio di esecuzione RemoteSigned o meno restrittivo.
Segui questi passaggi:
- Installa il modulo per il tuo account:
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Usa-Scope AllUserssolo se hai i diritti di amministratore e ti serve un'installazione condivisa. - Verifica il risultato con
Get-InstalledModule Microsoft.Graph. - Tieni presente che il modulo principale installa oltre 47 sotto-moduli. La pagina spiega che puoi installare solo quelli che ti servono e che
Microsoft.Graph.Authenticationviene installato insieme a loro. - Aggiorna più tardi con
Update-Module Microsoft.Graph. Un modulo non aggiornato è una delle cause segnalate di conflitti di versione.
L'installazione in una versione di PowerShell non la installa anche nell'altra, quindi esegui il comando nella versione che userai.
Ora accedi. La pagina sui comandi di autenticazione spiega che l'SDK supporta due tipi di accesso: delegato e app-only. L'accesso delegato agisce per conto di un utente che ha effettuato l'accesso, e le sue autorizzazioni sono gli ambiti. L'accesso app-only viene eseguito senza un utente, con un certificato, un segreto client o un'identità gestita.
Per i primi comandi, usa l'accesso delegato e richiedi un solo ambito in sola lettura:
Connect-MgGraph -Scopes "Sites.Read.All"
Si apre una finestra del browser per l'accesso. Per verificare cosa hai ottenuto, esegui Get-MgContext | Select -ExpandProperty Scopes. Microsoft documenta Get-MgContext come il comando che restituisce i dettagli della sessione corrente, come l'ID client, l'ID tenant, gli ambiti e il tipo di autenticazione. Al termine, esegui Disconnect-MgGraph. La pagina spiega che resti connesso finché non lo fai, perché i token vengono memorizzati nella cache con l'ambito predefinito CurrentUser. Aggiungi -ContextScope Process a Connect-MgGraph se vuoi che l'accesso valga solo per la sessione corrente.
Primi comandi per i siti di SharePoint
Il riferimento per Get-MgSite elenca i parametri principali: -Filter, -Search, -Property (alias -Select), -Top, -Sort e -All. Gli esempi della pagina sono brevi:
Get-MgSiteelenca i siti.Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"restituisce solo le raccolte siti radice, con due proprietà.
Da qui puoi costruire il resto:
- Elenco con paginazione. Esegui
Get-MgSite -Allper seguire tutte le pagine dei risultati. Senza-Allpotresti vedere solo la prima pagina. - Scegli le colonne. Aggiungi
-Property "id,displayName,webUrl"così l'output resta compatto e leggibile. - Cerca per parola chiave. Esegui
Get-MgSite -Search "finance". L'API di ricerca di Graph confronta il testo libero con diverse proprietà dei siti. - Recupera un sito. Esegui
Get-MgSite -SiteId <id>, dove l'ID è il valoreiddi un risultato precedente. Ha la forma di un nome host seguito da due GUID, separati da virgole.
Ognuno di questi cmdlet corrisponde a una chiamata REST. Get-MgSite -All legge la raccolta dei siti all'indirizzo https://graph.microsoft.com/v1.0/sites, l'URL che la documentazione REST indica per elencare i siti, e -Filter, -Search e -Property diventano opzioni di query su quell'URL. L'SDK ottiene i token tramite la Microsoft Authentication Library (MSAL). Se manca un cmdlet per una chiamata che ti serve, Invoke-MgGraphRequest può chiamare direttamente un URI. La pagina di risoluzione dei problemi lo usa per verificare l'URI alla base di un errore Bad request.
Due limiti sono importanti. Primo, l'endpoint di elenco di Graph restituisce i siti nella geografia predefinita dell'organizzazione. Per tutte le geografie, Microsoft indica l'API getAllSites, che corrisponde al cmdlet Get-MgAllSite. Secondo, l'API di ricerca può ordinare solo per createdDateTime.
Quali autorizzazioni ti servono? Microsoft Graph PowerShell e ambiti di SharePoint
Le autorizzazioni di Microsoft Graph sono la parte che sorprende i nuovi utenti. Per la lettura dei siti, la pagina dei cmdlet indica Sites.Read.All come la scelta con il minor privilegio e Sites.ReadWrite.All come quella con più privilegi. Scegli la prima, a meno che uno script non debba modificare qualcosa.
Non devi ricordare i nomi degli ambiti. Due comandi di supporto fanno la ricerca al posto tuo:
Find-MgGraphCommandmostra quali autorizzazioni richiede un cmdlet o un'API. La pagina sulla risoluzione dei problemi usa come esempioFind-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions.Find-MgGraphPermissiontrova le autorizzazioni per area o per nome, ad esempioFind-MgGraphPermission application. L'output mostra il tipo (delegate o applicazione), se il consenso deve essere concesso da un amministratore e una descrizione.
Nella documentazione c'è un punto su cui le fonti non concordano. La pagina REST per l'elenco dei siti mostra, per quella chiamata, solo autorizzazioni applicative e indica che l'accesso delegato non è supportato. La pagina dei cmdlet per Get-MgSite elenca invece entrambe. Testa la tua chiamata in un tenant non di produzione e leggi il testo dell'errore se fallisce. Non dare per scontato che la pagina dei cmdlet sia corretta per ogni chiamata.
Per i processi senza interazione serve un accesso solo app. Questo significa una registrazione app in Microsoft Entra, autorizzazioni applicative (chiamate anche autorizzazioni API) e il consenso di un amministratore. La pagina sulla risoluzione dei problemi precisa che le autorizzazioni applicative richiedono il consenso di un amministratore. Usa un certificato o un'identità gestita, non una password digitata.
Esempio: inventario dei siti inattivi in cinque comandi
I numeri di questo esempio sono inventati.
Un amministratore vuole un primo elenco dei siti che nessuno modifica da un anno.
Connect-MgGraph -Scopes "Sites.Read.All"$sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"- In questo esempio,
$sites.Countrestituisce 480. $old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }$old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation
Supponiamo che il file contenga 60 righe. Sono 60 su 480, cioè il 12,5 per cento: un elenco breve da rivedere con i proprietari dei siti. L'amministratore ha solo accesso in lettura e non ha modificato nulla. La data dell'ultima modifica di un sito non dimostra che nessuno lo usi, quindi l'elenco è un punto di partenza per fare domande, non una lista di eliminazione.
Errori comuni
- Connessione senza ambito. Un accesso senza l'ambito giusto porta a errori 403. Esegui
Get-MgContexte confronta gli ambiti con quelli richiesti dal cmdlet. - Chiedere ambiti di scrittura per un lavoro di sola lettura.
Sites.ReadWrite.Allè più di quanto serve a un report. Parti daSites.Read.All. - Dimenticare
-All. Senza questo parametro, un elenco può sembrare completo quando contiene solo la prima pagina. - Confondere le versioni del modulo. Microsoft consiglia il modulo v1.0 per gli script. Il modulo beta è in anteprima e può cambiare senza preavviso.
- Saltare l'aggiornamento. Una versione obsoleta di
Microsoft.Graphè una delle cause documentate di conflitti di versione. EseguiUpdate-Module Microsoft.Graphprima di cercare altre cause. - Restare connessi su un computer condiviso. I token vengono memorizzati nella cache. Esegui
Disconnect-MgGraphquando hai finito.
Come può aiutare il software
La maggior parte delle esigenze iniziali è coperta dagli strumenti che hai già. L'SDK di Microsoft Graph PowerShell gestisce letture ed esportazioni. Il centro di amministrazione di SharePoint mostra elenchi e impostazioni dei siti senza bisogno di codice. Excel o Power BI trasformano un CSV in un report che i proprietari dei siti possono leggere. Per le esecuzioni pianificate, Azure Automation può eseguire uno script con un'identità gestita.
Cerca eventuali lacune solo dopo il primo mese. Se ricostruisci a mano lo stesso inventario, di solito basta uno script salvato con una cartella di output fissa e un promemoria mensile.
Prossimo passo
Installa l'SDK, esegui Connect-MgGraph -Scopes "Sites.Read.All" ed esporta l'output di Get-MgSite -All in un CSV già oggi. Poi usa Find-MgGraphCommand sul prossimo cmdlet per conoscerne l'autorizzazione prima di eseguire attività di Microsoft Graph PowerShell per SharePoint in produzione.