M365Con 2027 – gratis online conferentie · 11–22 Jan 2027 · 120 sessions→ m365con.net

Blog · Mirko Peters

Microsoft Graph PowerShell voor SharePoint-beheerders: eerste commando's

By · · Updated

Microsoft Graph PowerShell voor SharePoint: installeer de SDK, meld je aan met de juiste scope, lijst sites op met Get-MgSite en los de 403-fouten op die beheerders als eerste tegenkomen.

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

Microsoft Graph PowerShell voor SharePoint betekent dat je de Graph SDK gebruikt om sites vanaf de opdrachtregel te lezen en te beheren. Je installeert één module, meldt je aan met Connect-MgGraph en een machtigingsscope, en voert cmdlets uit zoals Get-MgSite. Deze gids is bedoeld voor SharePoint-beheerders die het SharePoint-beheercentrum al kennen en een veilige eerste stap willen zetten richting scripting. Je installeert de SDK, meldt je aan met de kleinste scope die werkt, lijst sites op en leert de fouten lezen die als eerste verschijnen.

Belangrijkste punten

  • Microsoft Graph PowerShell is een SDK die de Graph-API's omhult. Daarom heeft elke opdracht eerst een aanmelding met Connect-MgGraph nodig, met de juiste machtigingsscopes.
  • Get-MgSite toont SharePoint-sites en heeft minimaal de machtiging Sites.Read.All nodig. Dat is de minst bevoegde optie die Microsoft ervoor documenteert.
  • Get-MgContext toont welke scopes je huidige sessie heeft. Dat is de snelste manier om een 403 Forbidden-fout te verklaren.
  • Find-MgGraphCommand en Find-MgGraphPermission laten zien welke machtiging een opdracht nodig heeft, zodat je geen scopenamen hoeft te raden.
  • Gedelegeerde aanmelding past bij iemand die achter het toetsenbord zit. App-only aanmelding met een certificaat of beheerde identiteit past bij taken die zonder toezicht draaien.

Wat Microsoft Graph PowerShell is en waarom beheerders het gebruiken

Microsoft Graph is de enkele API voor Microsoft 365-gegevens: gebruikers, groepen, bestanden, e-mail, Teams en SharePoint-sites. De Microsoft Graph PowerShell-SDK omhult de Graph-API in cmdlets. Je hoeft geen webaanroepen naar elk eindpunt te schrijven. Je voert Get-MgSite uit en krijgt siteobjecten terug.

Voor een SharePoint-beheerder heeft dit drie praktische voordelen.

  • Één tool voor alle diensten. Dezelfde aanmelding werkt voor sites, gebruikers en groepen. Een script kan sites opvragen en daarna hun eigenaren opzoeken.
  • Een machtigingsmodel dat je kunt lezen. Elke aanroep heeft benoemde machtigingen nodig, scopes genoemd. Je ziet welke scopes een sessie heeft en waarom een aanroep is geweigerd.
  • Een weg weg van oudere modules. De entiteitsnotities voor Microsoft Graph PowerShell beschrijven het als de vervanger van de uitgefaseerde Azure AD PowerShell- en MSOnline-modules.

De community-module PnP PowerShell is de andere veelgekozen keuze voor SharePoint-scripting. Volgens de documentatie praten sommige cmdlets ook met Graph. Graph PowerShell vervangt niet elke SharePoint-beheertool. Het dekt wat de Graph-API blootstelt. Sommige tenantinstellingen staan nog steeds in het SharePoint-beheercentrum of in andere modules. Zie Graph als één tool in je set, niet als de enige.

Stap 1: installeer de SDK en meld je aan

De installatiegids raadt PowerShell 7 of later aan op alle platforms. Windows PowerShell vereist versie 5.1 of later, .NET Framework 4.7.2 of later, en een uitvoeringsbeleid van RemoteSigned of minder beperkend.

Volg deze stappen:

  1. Installeer de module voor je eigen account: Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Gebruik -Scope AllUsers alleen als je beheerdersrechten hebt en een gedeelde installatie nodig hebt.
  2. Controleer het resultaat met Get-InstalledModule Microsoft.Graph.
  3. Let op: de hoofdmodule installeert meer dan 47 submodules. Volgens de pagina kun je alleen de submodules installeren die je nodig hebt, en Microsoft.Graph.Authentication komt er automatisch bij.
  4. Werk later bij met Update-Module Microsoft.Graph. Een verouderde module wordt genoemd als oorzaak van versieconflicten.

Installeren in de ene PowerShell-versie installeert de module niet in de andere, dus voer het commando uit in de versie die je gaat gebruiken.

Meld je nu aan. De pagina over authenticatiecommando's legt uit dat de SDK twee soorten toegang ondersteunt: gedelegeerd en app-only. Gedelegeerde toegang handelt namens een aangemelde gebruiker, en de machtigingen daarvan zijn scopes. App-only toegang draait zonder gebruiker, met een certificaat, een clientgeheim of een beheerde identiteit.

Gebruik voor je eerste commando's gedelegeerde toegang en vraag om één alleen-lezen scope:

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

Er opent een browservenster voor de aanmelding. Om te controleren wat je hebt gekregen, voer je Get-MgContext | Select -ExpandProperty Scopes uit. Microsoft documenteert Get-MgContext als het commando dat de details van je huidige sessie teruggeeft, zoals de client-ID, tenant-ID, scopes en het authenticatietype. Als je klaar bent, voer je Disconnect-MgGraph uit. Volgens de pagina blijf je aangemeld tot je dat doet, omdat tokens in de cache worden opgeslagen onder de standaardscope CurrentUser. Voeg -ContextScope Process toe aan Connect-MgGraph als de aanmelding alleen voor de huidige sessie moet gelden.

Eerste commando's voor SharePoint-sites

De referentie voor Get-MgSite somt de belangrijkste parameters op: -Filter, -Search, -Property (alias -Select), -Top, -Sort en -All. De voorbeelden op de pagina zelf zijn kort:

  • Get-MgSite geeft een lijst met sites weer.
  • Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null" geeft alleen de root-sitecollecties terug, met twee eigenschappen.

Bouw het vanaf daar verder op:

  1. Lijst met paginering. Voer Get-MgSite -All uit om alle pagina's met resultaten te doorlopen. Zonder -All zie je misschien alleen de eerste pagina.
  2. Kies de kolommen. Voeg -Property "id,displayName,webUrl" toe zodat de uitvoer klein en leesbaar blijft.
  3. Zoek op trefwoord. Voer Get-MgSite -Search "finance" uit. De Graph-zoek-API zoekt vrije tekst over meerdere siteseigenschappen.
  4. Haal één site op. Voer Get-MgSite -SiteId <id> uit, waarbij de ID de id-waarde is uit een eerder resultaat. Die heeft de vorm van een hostnaam, gevolgd door twee GUID's, gescheiden door komma's.

Elk van deze cmdlets komt overeen met een REST-aanroep. Get-MgSite -All leest de sites-verzameling op https://graph.microsoft.com/v1.0/sites, de URL die de REST-documentatie toont voor het opvragen van sites, en -Filter, -Search en -Property worden queryopties op die URL. De SDK haalt zijn tokens op via de Microsoft Authentication Library (MSAL). Als er voor een aanroep die je nodig hebt geen cmdlet bestaat, kan Invoke-MgGraphRequest een URI rechtstreeks aanroepen. De probleemoplossingspagina gebruikt dit om de URI achter een "Bad request"-fout te controleren.

Twee beperkingen zijn belangrijk. Ten eerste geeft het Graph-lijsteindpunt sites terug in de standaardgeografie van de organisatie. Voor alle geografieën verwijst Microsoft naar de getAllSites-API, die overeenkomt met de cmdlet Get-MgAllSite. Ten tweede kan de zoek-API alleen sorteren op createdDateTime.

Welke machtigingen heb je nodig? Microsoft Graph PowerShell- en SharePoint-scopes

Microsoft Graph-machtigingen zijn het onderdeel dat nieuwe gebruikers verrast. Voor het lezen van sites vermeldt de cmdletpagina Sites.Read.All als de minst bevoegde keuze en Sites.ReadWrite.All als de bevoegdere. Kies de eerste, tenzij een script iets moet wijzigen.

Je hoeft scopenamen niet uit je hoofd te kennen. Twee hulpcommando's zoeken ze voor je op:

  • Find-MgGraphCommand laat zien welke machtigingen een cmdlet of API nodig heeft. De pagina over probleemoplossing gebruikt Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions als voorbeeld.
  • Find-MgGraphPermission zoekt machtigingen op gebied of naam, bijvoorbeeld Find-MgGraphPermission application. De uitvoer toont het type (gedelegeerd of toepassing), of toestemming door een beheerder nodig is, en een beschrijving.

Let op één punt waarop de documentatie van zichzelf afwijkt. De REST-pagina voor het ophalen van sites toont voor deze aanroep alleen toepassingsmachtigingen en markeert gedelegeerde toegang als niet ondersteund. De cmdletpagina voor Get-MgSite vermeldt beide. Test je eigen aanroep in een niet-productietenant en lees de foutmelding als het misgaat. Ga er niet vanuit dat de cmdletpagina voor elke aanroep klopt.

Voor taken zonder gebruikersinteractie heb je app-only toegang nodig. Dat betekent een app-registratie in Microsoft Entra, toepassingsmachtigingen (ook API-machtigingen genoemd) en toestemming van een beheerder. De pagina over probleemoplossing stelt dat toepassingsmachtigingen toestemming van een beheerder vereisen. Gebruik een certificaat of een beheerde identiteit, geen getypt wachtwoord.

Voorbeeld: een inventaris van inactieve sites in vijf commando's

De getallen in dit voorbeeld zijn verzonnen.

Een beheerder wil een eerste lijst van sites waar al een jaar niemand iets aan heeft gewijzigd.

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

Stel dat het bestand 60 rijen bevat. Dat is 60 van de 480, oftewel 12,5 procent, een korte lijst om samen met de siteeigenaren door te nemen. De beheerder heeft alleen leesrechten en heeft niets gewijzigd. De datum van de laatste wijziging van een site bewijst niet dat niemand de site gebruikt. De lijst is dus een startpunt voor vragen, geen verwijderlijst.

Veelgemaakte fouten

  • Verbinden zonder scope. Een aanmelding zonder de juiste scope leidt tot 403-fouten. Voer Get-MgContext uit en vergelijk de scopes met wat de cmdlet nodig heeft.
  • Schrijfscopes vragen voor een leestaak. Sites.ReadWrite.All is meer dan een rapport nodig heeft. Begin met Sites.Read.All.
  • Vergeten van -All. Zonder deze parameter kan een lijst compleet lijken terwijl het alleen de eerste pagina is.
  • De modulversies door elkaar halen. Microsoft raadt de v1.0-module aan voor scripts. De bètamodule is in preview en kan zonder aankondiging wijzigen.
  • De update overslaan. Een oude versie van Microsoft.Graph is een bekende oorzaak van versieconflicten. Voer Update-Module Microsoft.Graph uit voordat je andere oorzaken gaat zoeken.
  • Aangemeld blijven op een gedeelde computer. Tokens worden in de cache opgeslagen. Voer Disconnect-MgGraph uit als je klaar bent.

Hoe software kan helpen

De meeste eerste behoeften worden al gedekt door tools die je al hebt. De Microsoft Graph PowerShell SDK verzorgt het lezen en exporteren. Het SharePoint-beheercentrum toont sitelijsten en instellingen zonder code. Excel of Power BI maakt van een CSV-bestand een rapport dat siteeigenaren kunnen lezen. Voor geplande uitvoeringen kan Azure Automation een script draaien met een beheerde identiteit.

Zoek pas na de eerste maand naar hiaten. Als je dezelfde inventaris steeds met de hand opnieuw opbouwt, is een opgeslagen script met een vaste uitvoermap en een maandelijkse herinnering meestal voldoende.

Volgende stap

Installeer de SDK, voer Connect-MgGraph -Scopes "Sites.Read.All" uit en exporteer vandaag nog de uitvoer van Get-MgSite -All naar een CSV-bestand. Gebruik daarna Find-MgGraphCommand bij je volgende cmdlet om de bijbehorende machtiging te leren kennen, voordat je taken voor SharePoint met Microsoft Graph PowerShell in productie uitvoert.

Volg de podcastSpotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS