Microsoft Graph PowerShell pour les administrateurs SharePoint : premières commandes
Par Mirko Peters · · Mis à jour
Microsoft Graph PowerShell pour SharePoint : installer le SDK, vous connecter avec le bon périmètre, lister les sites avec Get-MgSite et résoudre les erreurs 403 que rencontrent en premier les administrateurs.
Traduit automatiquement par IA à partir de l'article original. Lire l'original en anglais
Microsoft Graph PowerShell pour SharePoint consiste à utiliser le SDK Graph pour lire et gérer les sites depuis la ligne de commande. Vous installez un seul module, vous vous connectez avec Connect-MgGraph et un périmètre d’autorisation, puis vous exécutez des applets de commande comme Get-MgSite. Ce guide s’adresse aux administrateurs SharePoint qui connaissent déjà le Centre d’administration SharePoint et souhaitent aborder l’automatisation en toute sécurité. Vous allez installer le SDK, vous connecter avec le périmètre le plus restreint qui fonctionne, lister les sites et apprendre à interpréter les erreurs qui apparaissent en premier.
Points clés
- Microsoft Graph PowerShell est un SDK qui encapsule les API Graph ; chaque commande nécessite donc d’abord une connexion avec Connect-MgGraph et les bons périmètres d’autorisation.
- Get-MgSite liste les sites SharePoint et nécessite au minimum l’autorisation Sites.Read.All, qui est l’option la moins privilégiée documentée par Microsoft pour cette commande.
- Get-MgContext indique les périmètres dont dispose votre session actuelle, ce qui est le moyen le plus rapide d’expliquer une erreur 403 Forbidden.
- Find-MgGraphCommand et Find-MgGraphPermission indiquent l’autorisation dont a besoin une commande, afin que vous n’ayez pas à deviner les noms de périmètres.
- L’authentification déléguée convient à une personne devant son clavier, tandis que l’authentification en mode application uniquement, avec un certificat ou une identité managée, convient aux travaux non supervisés.
Ce qu’est Microsoft Graph PowerShell et pourquoi les administrateurs l’utilisent
Microsoft Graph est l’API unique pour les données Microsoft 365 : utilisateurs, groupes, fichiers, messagerie, Teams et sites SharePoint. Le SDK PowerShell Microsoft Graph encapsule l’API Graph dans des applets de commande. Vous n’avez pas à écrire de requêtes web pour chaque point de terminaison. Vous exécutez Get-MgSite et obtenez en retour des objets de site.
Pour un administrateur SharePoint, cela présente trois avantages concrets.
- Un seul outil pour plusieurs services. La même connexion fonctionne pour les sites, les utilisateurs et les groupes. Un script peut lister les sites, puis rechercher leurs propriétaires.
- Un modèle d’autorisations lisible. Chaque appel nécessite des autorisations nommées, appelées périmètres. Vous pouvez voir quels périmètres une session possède et pourquoi un appel a été refusé.
- Une alternative aux anciens modules. Les notes de l’entité Microsoft Graph PowerShell le décrivent comme le remplaçant des modules Azure AD PowerShell et MSOnline, désormais retirés.
Le module communautaire PnP PowerShell est l’autre choix courant pour l’automatisation SharePoint, et sa documentation précise que certaines applets de commande communiquent également avec Graph. Graph PowerShell ne remplace pas tous les outils d’administration SharePoint : il couvre ce que l’API Graph expose. Certains paramètres du locataire restent accessibles uniquement dans le Centre d’administration SharePoint ou via d’autres modules. Considérez Graph comme un outil parmi d’autres, et non comme le seul.
Étape 1 : installer le SDK et vous connecter
Le guide d’installation recommande PowerShell 7 ou version ultérieure sur toutes les plateformes. Windows PowerShell nécessite la version 5.1 ou ultérieure, .NET Framework 4.7.2 ou ultérieur, et une stratégie d’exécution définie sur RemoteSigned ou moins restrictive.
Suivez ces étapes :
- Installez le module pour votre propre compte :
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. N’utilisez-Scope AllUsersque si vous disposez de droits d’administrateur et si vous avez besoin d’une installation partagée. - Vérifiez le résultat avec
Get-InstalledModule Microsoft.Graph. - Sachez que le module principal installe plus de 47 sous-modules. La page indique que vous pouvez n’installer que ceux dont vous avez besoin, et que
Microsoft.Graph.Authenticationest installé avec eux. - Mettez-le à jour ultérieurement avec
Update-Module Microsoft.Graph. Un module obsolète figure parmi les causes recensées de conflits de versions.
L’installation dans une version de PowerShell n’installe pas le module dans l’autre. Exécutez donc la commande dans la version que vous utiliserez.
Connectez-vous maintenant. La page consacrée aux commandes d’authentification explique que le SDK prend en charge deux types d’accès : délégué et application seule. L’accès délégué agit au nom d’un utilisateur connecté, et ses autorisations sont des étendues (scopes). L’accès application seule s’exécute sans utilisateur, avec un certificat, un secret client ou une identité managée.
Pour vos premières commandes, utilisez l’accès délégué et demandez une seule étendue en lecture seule :
Connect-MgGraph -Scopes "Sites.Read.All"
Une fenêtre de navigateur s’ouvre pour l’authentification. Pour vérifier ce que vous avez obtenu, exécutez Get-MgContext | Select -ExpandProperty Scopes. Microsoft décrit Get-MgContext comme la commande qui renvoie les détails de votre session en cours, comme l’ID client, l’ID de locataire, les étendues et le type d’authentification. Une fois terminé, exécutez Disconnect-MgGraph. La page précise que vous restez connecté tant que vous ne le faites pas, car les jetons sont mis en cache sous la portée CurrentUser par défaut. Ajoutez -ContextScope Process à Connect-MgGraph si vous souhaitez que la connexion ne dure que pour la session en cours.
Premières commandes pour les sites SharePoint
La référence de Get-MgSite répertorie les principaux paramètres : -Filter, -Search, -Property (alias -Select), -Top, -Sort et -All. Les exemples de la page sont courts :
Get-MgSiteliste les sites.Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"ne renvoie que les collections de sites racines, avec deux propriétés.
Partez de là pour aller plus loin :
- Lister avec pagination. Exécutez
Get-MgSite -Allpour parcourir toutes les pages de résultats. Sans-All, vous ne verrez peut-être que la première page. - Choisissez les colonnes. Ajoutez
-Property "id,displayName,webUrl"pour que la sortie reste réduite et lisible. - Recherchez par mot-clé. Exécutez
Get-MgSite -Search "finance". L’API de recherche Graph retrouve le texte libre dans plusieurs propriétés de site. - Obtenez un site. Exécutez
Get-MgSite -SiteId <id>, où l’ID est la valeuridd’un résultat précédent. Il a la forme d’un nom d’hôte suivi de deux GUID, séparés par des virgules.
Chaque cmdlet correspond à un appel REST. Get-MgSite -All lit la collection de sites à l’adresse https://graph.microsoft.com/v1.0/sites, l’URL que la documentation REST indique pour lister les sites, et -Filter, -Search et -Property deviennent des options de requête sur cette URL. Le SDK obtient ses jetons via la Microsoft Authentication Library (MSAL). Si un cmdlet manque pour un appel dont vous avez besoin, Invoke-MgGraphRequest peut appeler directement un URI. La page de dépannage l’utilise pour vérifier l’URI à l’origine d’une erreur Bad request.
Deux limites sont importantes. D’abord, le point de terminaison de liste Graph renvoie les sites de la zone géographique par défaut de l’organisation. Pour toutes les zones géographiques, Microsoft renvoie vers l’API getAllSites, qui correspond au cmdlet Get-MgAllSite. Ensuite, l’API de recherche ne peut trier que par createdDateTime.
Quelles autorisations vous faut-il ? Microsoft Graph PowerShell et étendues SharePoint
Les autorisations Microsoft Graph sont la partie qui surprend les nouveaux utilisateurs. Pour la lecture de sites, la page des cmdlets indique Sites.Read.All comme le choix le moins privilégié et Sites.ReadWrite.All comme le plus privilégié. Choisissez le premier, sauf si un script doit modifier quelque chose.
Inutile de mémoriser les noms de périmètres. Deux commandes d’aide permettent de les retrouver :
Find-MgGraphCommandindique les autorisations requises par une cmdlet ou une API. La page de dépannage utiliseFind-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissionscomme exemple.Find-MgGraphPermissionrecherche des autorisations par domaine ou par nom, par exempleFind-MgGraphPermission application. La sortie indique le type (déléguée ou application), si le consentement doit être donné par un administrateur, ainsi qu’une description.
La documentation présente une divergence sur un point. La page REST de liste des sites n’affiche, pour cet appel, que les autorisations d’application et indique que l’accès délégué n’est pas pris en charge. La page de la cmdlet Get-MgSite mentionne les deux. Testez votre propre appel dans un locataire de non-production et lisez le texte de l’erreur en cas d’échec. Ne partez pas du principe que la page de la cmdlet est exacte pour tous les appels.
Pour les tâches automatisées sans intervention, vous avez besoin d’un accès en mode application uniquement. Cela suppose une inscription d’application dans Microsoft Entra, des autorisations d’application (également appelées autorisations d’API) et un consentement administrateur. La page de dépannage indique que les autorisations d’application nécessitent un consentement administrateur. Utilisez un certificat ou une identité managée, et non un mot de passe saisi.
Exemple : un inventaire des sites inactifs en cinq commandes
Les chiffres de cet exemple sont fictifs.
Un administrateur souhaite obtenir une première liste des sites que personne n’a modifiés depuis un an.
Connect-MgGraph -Scopes "Sites.Read.All"$sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"$sites.Countrenvoie 480 dans cet exemple.$old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }$old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation
Supposons que le fichier contienne 60 lignes. Cela représente 60 sites sur 480, soit 12,5 %, une liste courte à examiner avec les propriétaires des sites. L’administrateur dispose uniquement d’un accès en lecture et n’a rien modifié. La date de dernière modification d’un site ne prouve pas que personne ne l’utilise : la liste constitue donc un point de départ pour poser des questions, et non une liste de suppression.
Erreurs courantes
- Connexion sans périmètre. Une connexion sans le bon périmètre entraîne des erreurs 403. Exécutez
Get-MgContextet comparez les périmètres avec ceux dont la cmdlet a besoin. - Demander des périmètres en écriture pour une tâche de lecture.
Sites.ReadWrite.Alldépasse les besoins d’un rapport. Commencez parSites.Read.All. - Oublier
-All. Sans ce paramètre, une liste peut sembler complète alors qu’elle ne contient que la première page. - Confondre les versions des modules. Microsoft recommande le module v1.0 pour les scripts. Le module bêta est en préversion et peut changer sans préavis.
- Oublier la mise à jour. Une ancienne version de
Microsoft.Graphest une cause connue de conflits de versions. ExécutezUpdate-Module Microsoft.Graphavant de rechercher d’autres causes. - Rester connecté sur un poste partagé. Les jetons sont mis en cache. Exécutez
Disconnect-MgGraphune fois votre travail terminé.
Comment les logiciels peuvent aider
La plupart des besoins d’une première utilisation sont couverts par des outils que vous possédez déjà. Le SDK PowerShell de Microsoft Graph gère la lecture et les exports. Le Centre d’administration SharePoint affiche les listes et les paramètres des sites sans code. Excel ou Power BI transforme un fichier CSV en rapport lisible par les propriétaires des sites. Pour les exécutions planifiées, Azure Automation peut lancer un script avec une identité managée.
Ne cherchez les lacunes qu’après le premier mois. Si vous reconstituez manuellement le même inventaire, un script enregistré avec un dossier de sortie fixe et un rappel mensuel suffit généralement.
Prochaine étape
Installez le SDK, exécutez Connect-MgGraph -Scopes "Sites.Read.All" et exportez le résultat de Get-MgSite -All vers un fichier CSV dès aujourd’hui. Utilisez ensuite Find-MgGraphCommand sur votre prochaine cmdlet pour connaître son autorisation avant d’exécuter des tâches SharePoint avec Microsoft Graph PowerShell en production.