Microsoft 365 / Microsoft Graph PowerShell: esportare utenti in CSV e gestire licenze
Microsoft Graph PowerShell ti consente di interrogare gli utenti di Microsoft 365 e automatizzare la gestione degli account e delle licenze. Inizia con installare i moduli richiesti → connettersi con autorizzazioni di lettura → confermare l'organizzazione di destinazione → esportare gli utenti in un file CSV (valori separati da virgola). L'esercizio in sola lettura e gli esempi di modifica dell'account o della licenza di seguito richiedono autorizzazioni diverse e hanno effetti diversi, quindi eseguili separatamente.
Che cos'è Microsoft Graph PowerShell?
Microsoft Graph è un'API (Application Programming Interface, un'interfaccia per la comunicazione tra programmi) che gestisce i dati da Microsoft Entra ID, Teams, SharePoint e altro ancora. Il Graph PowerShell SDK (Software Development Kit) ti permette di usare questa API tramite comandi PowerShell. Il nome attuale del servizio di directory, precedentemente indicato come Azure Active Directory o Azure AD nei documenti più vecchi, è Microsoft Entra ID.
L'installazione di Graph non significa che puoi utilizzare tutti i comandi di gestione di Microsoft 365. Alcuni compiti, come i comandi di gestione specifici di Exchange Online, richiedono moduli e connessioni separati. Questo articolo copre Autenticazione Delegata Interattiva utilizzando il modulo Microsoft Graph v1.0. L'autenticazione solo app per attività pianificate non presenziate richiede considerazioni progettuali separate come le autorizzazioni dell'app e i certificati ed è diversa dall'esecuzione di attività pianificate utilizzando gli stessi esempi di accesso utente.
Requisiti e installazione del modulo
Microsoft consiglia PowerShell 7 o versioni successive. Esegui i seguenti esercizi in un ambiente PowerShell 7 supportato. Windows PowerShell 5.1 richiede .NET Framework separato, PowerShellGet e altri prerequisiti, e i moduli installati in una versione non vengono installati automaticamente in un'altra versione. Per prima cosa, verifica i requisiti di installazione del SDK.
- Apri PowerShell su un PC di amministrazione approvato dall'organizzazione. Controlla la sua versione con
$PSVersionTable.PSVersion. - Nel centro di amministrazione Microsoft Entra, verifica l'ID tenant di destinazione sotto Entra ID → Overview. Questo è particolarmente importante se il tuo account ha accesso a più organizzazioni.
- Verifica il consenso amministrativo alle autorizzazioni Graph e, separatamente, il tuo ruolo amministrativo. Usa un account aziendale o scolastico della tua organizzazione, anziché un account Microsoft personale.
- Crea una cartella protetta per memorizzare i file dei risultati. Poiché l'elenco degli utenti contiene nomi e indirizzi degli account, non usare archiviazioni pubbliche o cartelle web pubbliche.
Per installare solo i moduli necessari per l'ambito dell'utente attuale, esegui come segue. Se appare un messaggio di conferma dell'installazione, verifica il repository e i pacchetti. È anche possibile installare il modulo completo Microsoft.Graph, ma per questo esercizio, i sottomoduli elencati di seguito sono sufficienti.
Install-Module -Name Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions -Scope CurrentUser -Repository PSGallery
Dopo l'installazione, controlla le versioni disponibili e i nomi dei comandi usando il comando seguente. A questo passo, non si connette ai dati dell'organizzazione.
Get-Module -ListAvailable Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions | Select-Object Name,Version
Get-Command Connect-MgGraph,Get-MgUser,Get-MgSubscribedSku,Set-MgUserLicense
Se moduli o script sono bloccati a causa della policy di esecuzione, prima controlla la sezione della policy di esecuzione. Non considerare un errore di policy come un problema simile a un errore di autorizzazione 403.
Distinguere le autorizzazioni di connessione e i ruoli di amministratore
L'autenticazione delegata è un metodo che funziona per conto dell'utente connesso. -Scopes è l'ambito di autorizzazione di Graph richiesto dall'app e deve anche soddisfare l'ambito di ruolo/obiettivo dell'amministratore connesso e il consenso dell'amministratore. Scrivere semplicemente un nome in -Scopes non approva automaticamente tale autorizzazione né crea un ruolo amministrativo.
| Attività | Autorizzazioni di Graph richieste nell'esempio | Controlli aggiuntivi |
|---|---|---|
| Visualizzare l'elenco utenti e gli attributi specificati | User.Read.All |
Consenso dell'amministratore e limitazione degli attributi da interrogare |
| Interrogare gli SKU di sottoscrizione e le licenze degli utenti | LicenseAssignment.Read.All |
Ruoli supportati dall'API, come Lettori di Directory |
| Creare utenti cloud | User.Create |
Permessi di consenso dell'amministratore e gestione degli utenti e dei target |
| Assegnare e revocare licenze | LicenseAssignment.ReadWrite.All |
Ruoli supportati, come Amministratore di Licenze |
Per la pratica di lettura, non è necessario richiedere permessi di modifica del gruppo o permessi di scrittura completi della directory insieme. Le autorizzazioni delegate rispetto a quelle dell'applicazione e i requisiti di consenso dell'amministratore possono essere controllati in Riferimento permessi Microsoft Graph.
Per testare i singoli comandi di query, connettiti come mostrato di seguito. L'ID del tenant che inserisci deve essere il valore effettivo confermato nella tua organizzazione e, dopo l'accesso, controlla Account·TenantId·Scopes. Il metodo di accesso può utilizzare un browser o la finestra di autenticazione di Windows a seconda della versione e dell'ambiente installati.
$tenantId = Read-Host 'ID del tenant di destinazione'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,AuthType,Scopes
-ContextScope Process limita il contesto di autenticazione al processo PowerShell corrente. Quando Connect-MgGraph viene chiamato senza ambiti espliciti, verifica il contesto effettivo piuttosto che assumere che il suo permesso sia sempre User.Read. Per cambiare account o ambiti, esegui Disconnect-MgGraph e riconnettiti con gli ambiti richiesti. Vedi la guida di autenticazione Graph PowerShell.
Esempio completo di ricerca utente e salvataggio in CSV
Get-MgUser -All recupera continuamente elenchi di utenti restituiti in pagine. Tuttavia, questo non significa che riceva automaticamente tutte le proprietà. Select-Object * espande solo le proprietà degli oggetti già ricevuti e i valori non inclusi nel ritorno predefinito devono essere richiesti al server con -Property. Questa differenza è spiegata in Descrizione di Get-MgUser.
Salva il seguente codice completo come UTF-8 con m365-users-report.ps1. Lo script legge le informazioni degli utenti, crea un CSV con timestamp nella stessa cartella e disconnette la sessione. Non modifica account o licenze. Se hai svolto pratiche di connessione precedenti, termina prima con Disconnect-MgGraph e poi esegui questo.
param(
[Parameter(Mandatory)]
[Guid]$TenantId
)
$ErrorActionPreference = 'Stop'
$connected = $false
$file = Join-Path $PSScriptRoot ("m365-users-{0}.csv" -f (Get-Date -Format 'yyyyMMdd-HHmmss'))
try {
Connect-MgGraph -TenantId $TenantId.ToString() -Scopes 'User.Read.All' -ContextScope Process -NoWelcome
$connected = $true
$context = Get-MgContext
if ($context.TenantId -ne $TenantId.ToString()) {
throw 'Il tenant connesso non corrisponde al tenant richiesto.'
}
$properties = 'Id','DisplayName','UserPrincipalName','Mail','AccountEnabled','UsageLocation','AssignedLicenses'
$users = @(Get-MgUser -All -Property $properties)
if ($users.Count -eq 0) {
throw 'Nessun utente restituito. Verificare connessione e autorizzazioni.'
}
$report = @($users | Select-Object Id,DisplayName,UserPrincipalName,Mail,AccountEnabled,UsageLocation,
@{Name='AssignedSkuCount';Expression={ @($_.AssignedLicenses | Where-Object { $null -ne $_ }).Count }})
$report | Export-Csv -Path $file -NoTypeInformation -Encoding utf8BOM -NoClobber
Write-Host ("Salvato: {0} / Numero di utenti: {1}" -f $file, $report.Count)
$report | Select-Object -First 5 | Format-Table DisplayName,UserPrincipalName,AssignedSkuCount -AutoSize
}
finally {
if ($connected) {
Disconnect-MgGraph -ErrorAction SilentlyContinue | Out-Null
}
}
Dopo esserti spostato nella cartella in cui si trova il file in PowerShell, esegui come segue. Adatta il percorso del file alla posizione effettivamente salvata e incolla l'ID del tenant della tua organizzazione nel campo di input.
$targetTenant = Read-Host 'ID del tenant di destinazione'
.\m365-users-report.ps1 -TenantId $targetTenant
Se riesce, verranno visualizzati il percorso del CSV e il numero di utenti, e i primi cinque utenti saranno mostrati sullo schermo. Confronta il numero di righe nel file con il numero di utenti sullo schermo e verifica il nome visualizzato, l'indirizzo di accesso, la posizione d'uso e la licenza di un account di test noto rispetto al centro amministrativo. AssignedSkuCount rappresenta il numero di SKU di prodotto assegnati, non il numero di singoli servizi o postazioni acquistate.
Anche se ci sono utenti con un Mail vuoto, non si deve subito presumere un fallimento della query. Il nome utente, UserPrincipalName, e l'indirizzo email sono attributi diversi. Anche se AccountEnabled è vero, l'accesso effettivo o l'uso del servizio può essere limitato a causa di licenze, politiche o valutazioni di rischio. Non si deve concludere da questo rapporto da solo che un utente abbia effettuato l'accesso di recente o stia svolgendo normalmente il lavoro.
Se non vengono restituiti risultati o la generazione del CSV fallisce, non contrassegnare come completato. Controlla i permessi per il percorso di output, i file con lo stesso nome, i blocchi dei file e i messaggi di errore. Poiché il rapporto riflette i risultati della query al momento dell'esecuzione, se gli account sono cambiati, eseguilo di nuovo per il confronto e gestisci i file precedenti secondo la politica di conservazione della tua organizzazione.
Interrogazione dei prodotti con licenza e delle assegnazioni degli utenti
SKU (Stock Keeping Unit, identificatore di prodotto) è l'unità utilizzata qui per distinguere i prodotti con licenza. SkuPartNumber è la stringa di identificazione del prodotto e SkuId è l'identificatore globale unico del prodotto (GUID) utilizzato nei comandi Graph. Quando si modifica l'assegnazione di un utente, distinguerla in modo da non inserire l'ID dell'oggetto sottoscrizione o l'ID del piano di servizio al posto dell'ID SKU.
L'intero script CSV si disconnette alla fine, quindi durante l'esecuzione dei singoli comandi sottostanti, riconnettersi ogni volta. Oltre alle autorizzazioni di lettura, il ruolo supportato da quell'operazione è richiesto per interrogare le SKU delle sottoscrizioni. Consultare Ruoli e Autorizzazioni per l'Interrogazione delle SKU delle Sottoscrizioni.
$tenantId = Read-Host 'ID del tenant di destinazione'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All','LicenseAssignment.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
Get-MgSubscribedSku -All | Select-Object SkuPartNumber,SkuId,CapabilityStatus,ConsumedUnits,@{Name='EnabledUnits';Expression={$_.PrepaidUnits.Enabled}}
$userId = Read-Host 'Nome principale utente (UPN) o ID oggetto da verificare'
Get-MgUserLicenseDetail -UserId $userId -All | Select-Object SkuPartNumber,SkuId,ServicePlans
ConsumedUnits è il numero di licenze consumate, e PrepaidUnits.Enabled sono le unità fornite come disponibili. Poiché potrebbero esserci stati sospesi, avvisi e condizioni del prodotto, non interpretare immediatamente la semplice differenza come la quantità fatturata o i licenze disponibili per tutti i prodotti. I dettagli effettivi di acquisto e fatturazione devono essere confermati separatamente attraverso Procedura di Riconciliazione di Abbonamento, Fatturazione e Quantità di Licenze.
Get-MgUserLicenseDetail include licenze assegnate direttamente ed ereditate dai gruppi. Non puoi distinguere la causa dell'assegnazione basandoti solo su questo risultato. Per le assegnazioni basate su gruppi, controlla inoltre il centro di amministrazione o le informazioni sullo stato dell'assegnazione. In Dettagli Licenze Utente API, puoi anche verificare i permessi delegati e i ruoli supportati.
Eseguire le operazioni di modifica dell'utente e della licenza separatamente.
Il seguente esempio mostra un'operazione che modifica i dati organizzativi. Non eseguirla in batch immediatamente dopo il report di lettura; riconnettersi con i permessi necessari dopo aver preparato un utente di test approvato e i record prima delle modifiche. L'opzione -WhatIf qui sotto consente di visualizzare l'operazione che si desidera eseguire e non è un test simulato che verifica tutte le validazioni del server, i permessi e le condizioni della licenza.
Creare un utente di test cloud.
Usa questo metodo solo per utenti gestiti direttamente nel cloud. In un’organizzazione sincronizzata, verifica prima se gli account devono essere creati nella directory di origine. Scegli un nome principale utente (UPN, il nome di accesso) univoco in un dominio verificato del tenant e una password temporanea conforme ai criteri. Creare un membro è diverso da invitare un collaboratore esterno. Consulta i requisiti e le autorizzazioni per creare utenti, compresa l’autorizzazione minima User.Create, e verifica ruolo e ambito amministrativi.
Disconnect-MgGraph
$tenantId = Read-Host 'ID del tenant di destinazione'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Create','User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
$upn = Read-Host 'UPN del nuovo utente di test (dominio verificato)'
$nickname = Read-Host 'Alias di posta (ad esempio, graph-test01)'
$securePassword = Read-Host 'Password temporanea conforme ai criteri' -AsSecureString
$params = @{
AccountEnabled = $true
DisplayName = 'Utente di test Graph'
UserPrincipalName = $upn
MailNickname = $nickname
PasswordProfile = @{
Password = [System.Net.NetworkCredential]::new('', $securePassword).Password
ForceChangePasswordNextSignIn = $true
}
}
try {
New-MgUser -BodyParameter $params -WhatIf
}
finally {
$params.PasswordProfile.Password = $null
Remove-Variable securePassword
}
Dopo aver verificato input e destinazioni, per creare effettivamente l'utente, rimuovere -WhatIf dal codice ed eseguirlo di nuovo. Non codificare mai le password direttamente nelle stringhe della riga di comando o nei file di script. Poiché le richieste SDK richiedono valori di password in testo semplice, non usare l'output di debug o la registrazione del corpo della richiesta per questo compito e distribuisci le password temporanee attraverso i canali approvati dall'organizzazione.
Dopo la creazione, verifica nuovamente l'account usando Get-MgUser -UserId $upn -Property Id,DisplayName,UserPrincipalName,AccountEnabled. Creare semplicemente un utente non completa automaticamente le licenze delle app, le caselle di posta o l'appartenenza ai gruppi. Eliminare un account di test richiede anche una revisione dei dati simile a quella necessaria per eliminare un account aziendale. Controlla procedure di offboarding e consegna dei dati, quindi rivedi e organizza il target e l'ambito recuperabile nel centro di amministrazione.
Rimuovere le licenze assegnate direttamente
Prima di rimuovere una licenza, controllare l'utente, il prodotto, se è stato assegnato direttamente o tramite gruppo e i requisiti di conservazione dei dati. In questo esempio, -RemoveLicenses passa un array di stringhe ID SKU, ma non include una tabella hash nel formato @{SkuId=...}. Utilizzare -AddLicenses @() insieme quando non ci sono ulteriori prodotti da aggiungere. Controllare la sintassi Set-MgUserLicense.
Disconnect-MgGraph
$tenantId = Read-Host 'ID del tenant di destinazione'
Connect-MgGraph -TenantId $tenantId -Scopes 'LicenseAssignment.ReadWrite.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
$userId = Read-Host 'UPN o ID oggetto per la rimozione della licenza'
$skuId = [Guid](Read-Host 'SkuId verificato della licenza da rimuovere')
Set-MgUserLicense -UserId $userId -AddLicenses @() -RemoveLicenses @($skuId.ToString()) -WhatIf
Esegui la modifica dopo approvazione e verifica dell’account di destinazione, rimuovendo -WhatIf. Servono sia il consenso per LicenseAssignment.ReadWrite.All sia un ruolo supportato, ad esempio Amministratore delle licenze. Per una licenza ereditata da un gruppo, verifica l’assegnazione al gruppo; la rimozione diretta dal singolo utente non sostituisce questa gestione. Consulta autorizzazioni, ruoli e formato della richiesta di assegnazione delle licenze.
Dopo la modifica, riconnettiti con i permessi di lettura necessari e confronta i dettagli della licenza con il centro di gestione. Durante il rollback, è necessario verificare i licenze disponibili, le posizioni di utilizzo e i piani di servizio precedentemente disabilitati da riassegnare alla configurazione originale. Non dare per scontato che la riassegnazione della licenza annulli tutte le eliminazioni di dati eseguite precedentemente. È importante completare la conservazione e il trasferimento dei dati prima della rimozione della licenza.
Verifica la politica di esecuzione di Windows e il rollback
Le politiche di esecuzione sono condizioni per l'esecuzione di script e moduli. Se si verifica un errore di blocco in Windows, verificare la politica effettiva e i valori per ambito.
Get-ExecutionPolicy
Get-ExecutionPolicy -List
Solo se la politica organizzativa lo consente e l'ambito utente corrente necessita modifiche, registrare i valori precedenti e rivedere RemoteSigned. Se le impostazioni sono già consentite, non modificarle solo per adattarle al formato. Se MachinePolicy e UserPolicy della politica del gruppo organizzativo hanno la precedenza, verificare con la persona responsabile e non bypassare.
$previousUserPolicy = Get-ExecutionPolicy -Scope CurrentUser
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Get-ExecutionPolicy -List
Per ripristinare il valore originale al termine, esegui il comando seguente nella stessa sessione. In una nuova finestra, usa il valore effettivamente registrato prima. RemoteSigned non rende affidabile tutto il codice ricevuto da Internet. Consulta gli ambiti e le priorità dei criteri di esecuzione.
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy $previousUserPolicy
Errori comuni e terminazione delle attività
| Sintomi | Sequenza di Verifica |
|---|---|
| Comando Non Riconosciuto | Controlla la versione di PowerShell in esecuzione e la posizione di installazione del modulo. Get-MgUser si trova in Microsoft.Graph.Users. Usa Get-Command per individuare il comando e distinguere tra errori di installazione e di importazione. |
| 403 o Privilegi Insufficienti | Verifica l'account connesso, il tenant, gli ambiti, il consenso dell'amministratore e i ruoli supportati per l'API. Non aggiungere permessi di scrittura completi per impostazione predefinita. |
| Impossibile Trovare Utente o Oggetto | Controlla l'organizzazione e l'UPN/ID oggetto, e lo stato di eliminazione/sincronizzazione. Assicurati che il nome dell'account non provenga da un tenant diverso. |
| La proprietà è vuota | Distinguere se la proprietà è stata richiesta con -Property, se l'account ha effettivamente un valore e se la proprietà richiede permessi separati. |
| Accesso bloccato | Registrare i codici di errore e i timestamp, e controllare l'accesso condizionale, l'autenticazione multifattore (MFA), i metodi di autenticazione consentiti e i registri di accesso. Non disabilitare le politiche di sicurezza per un accesso riuscito. |
Registrare insieme la versione dell'installazione, gli errori dettagliati dei comandi, l'ID della richiesta e il momento di occorrenza può aiutare con la riproduzione e le richieste di supporto. Anche quando si utilizza il metodo in diagnosi degli errori di Graph PowerShell, non condividere i registri contenenti token, password o informazioni personali così come sono.
Dopo aver completato gli esercizi con i singoli comandi, disconnettersi e controllare la posizione di archiviazione dei file dei risultati. Effettuare il logout è diverso dall'annullare le modifiche all'account o alla licenza che sono già state eseguite.
Disconnect-MgGraph




