Microsoft Graph PowerShell für SharePoint-Admins: die ersten Befehle
Von Mirko Peters · · Aktualisiert
Microsoft Graph PowerShell für SharePoint: SDK installieren, mit dem richtigen Scope anmelden, Websites mit Get-MgSite auflisten und die 403-Fehler beheben, auf die Admins zuerst stoßen.
Automatisch mit KI aus dem Originalbeitrag übersetzt. Englisches Original lesen
Microsoft Graph PowerShell für SharePoint bedeutet, das Graph-SDK zu nutzen, um Websites über die Kommandozeile zu lesen und zu verwalten. Sie installieren ein einziges Modul, melden sich mit Connect-MgGraph und einem Berechtigungs-Scope an und führen Cmdlets wie Get-MgSite aus. Dieser Leitfaden richtet sich an SharePoint-Admins, die das SharePoint Admin Center bereits kennen und einen sicheren ersten Einstieg in die Skripterstellung suchen. Sie installieren das SDK, melden sich mit dem kleinstmöglichen funktionierenden Scope an, listen Websites auf und lernen, die Fehler zu lesen, die als Erstes auftreten.
Das Wichtigste in Kürze
- Microsoft Graph PowerShell ist ein SDK, das die Graph APIs kapselt. Daher braucht jeder Befehl zuerst eine Anmeldung mit Connect-MgGraph und den passenden Berechtigungs-Scopes.
- Get-MgSite listet SharePoint-Websites auf und benötigt mindestens die Berechtigung Sites.Read.All. Das ist die geringste Berechtigung, die Microsoft dafür dokumentiert.
- Get-MgContext zeigt, welche Scopes Ihre aktuelle Sitzung besitzt. Das ist der schnellste Weg, einen 403-Fehler Forbidden zu erklären.
- Find-MgGraphCommand und Find-MgGraphPermission zeigen Ihnen, welche Berechtigung ein Befehl benötigt, sodass Sie Scope-Namen nicht raten müssen.
- Die delegierte Anmeldung eignet sich für eine Person am Rechner, während die reine App-Anmeldung mit Zertifikat oder verwalteter Identität für unbeaufsichtigte Aufträge geeignet ist.
Was Microsoft Graph PowerShell ist und warum Admins es nutzen
Microsoft Graph ist die zentrale API für Microsoft 365-Daten: Benutzer, Gruppen, Dateien, E-Mails, Teams und SharePoint-Websites. Das Microsoft Graph PowerShell SDK kapselt die Graph API in Cmdlets. Sie schreiben keine Webanfragen an jeden Endpunkt. Sie führen Get-MgSite aus und erhalten Website-Objekte zurück.
Für einen SharePoint-Admin bringt das drei praktische Vorteile.
- Ein Werkzeug für alle Dienste. Dieselbe Anmeldung funktioniert für Websites, Benutzer und Gruppen. Ein Skript kann Websites auflisten und anschließend deren Besitzer abfragen.
- Ein nachvollziehbares Berechtigungsmodell. Jeder Aufruf benötigt benannte Berechtigungen, sogenannte Scopes. Sie können sehen, welche Scopes eine Sitzung besitzt und warum ein Aufruf abgelehnt wurde.
- Ein Weg weg von älteren Modulen. Die Entitätsnotizen zu Microsoft Graph PowerShell beschreiben es als Nachfolger der eingestellten Module Azure AD PowerShell und MSOnline.
Das community-basierte Modul PnP PowerShell ist die andere gängige Wahl für das Skripten in SharePoint. Seine Dokumentation weist darauf hin, dass einige Cmdlets ebenfalls mit Graph kommunizieren. Graph PowerShell ersetzt nicht jedes SharePoint-Admin-Werkzeug. Es deckt ab, was die Graph API bereitstellt. Einige Mandanteneinstellungen liegen weiterhin im SharePoint Admin Center oder in anderen Modulen. Betrachten Sie Graph als ein Werkzeug in Ihrem Set, nicht als das einzige.
Schritt 1: SDK installieren und anmelden
Der Installationsleitfaden empfiehlt auf allen Plattformen PowerShell 7 oder neuer. Windows PowerShell benötigt Version 5.1 oder neuer, .NET Framework 4.7.2 oder neuer und eine Ausführungsrichtlinie von RemoteSigned oder weniger restriktiv.
Gehen Sie so vor:
- Installieren Sie das Modul für Ihr eigenes Konto:
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Verwenden Sie-Scope AllUsersnur, wenn Sie Administratorrechte haben und eine gemeinsame Installation benötigen. - Prüfen Sie das Ergebnis mit
Get-InstalledModule Microsoft.Graph. - Beachten Sie, dass das Hauptmodul mehr als 47 Untermodule installiert. Laut der Seite können Sie nur die Untermodule installieren, die Sie benötigen, und
Microsoft.Graph.Authenticationwird mit ihnen mitinstalliert. - Aktualisieren Sie später mit
Update-Module Microsoft.Graph. Ein veraltetes Modul wird als Ursache für Versionskonflikte aufgeführt.
Die Installation in einer PowerShell-Version gilt nicht für die andere. Führen Sie den Befehl daher in der Version aus, die Sie tatsächlich verwenden werden.
Melden Sie sich jetzt an. Auf der Seite zu den Authentifizierungsbefehlen wird erläutert, dass das SDK zwei Zugriffsarten unterstützt: delegiert und nur-App. Delegierter Zugriff handelt im Namen eines angemeldeten Benutzers, und seine Berechtigungen sind Bereiche (Scopes). Nur-App-Zugriff läuft ohne Benutzer, mit einem Zertifikat, einem Clientschlüssel oder einer verwalteten Identität.
Verwenden Sie für Ihre ersten Befehle den delegierten Zugriff und fordern Sie einen schreibgeschützten Bereich an:
Connect-MgGraph -Scopes "Sites.Read.All"
Ein Browserfenster öffnet sich zur Anmeldung. Um zu prüfen, was Sie erhalten haben, führen Sie Get-MgContext | Select -ExpandProperty Scopes aus. Microsoft beschreibt Get-MgContext als Befehl, der die Details Ihrer aktuellen Sitzung zurückgibt, etwa Client-ID, Mandanten-ID, Bereiche und Authentifizierungstyp. Wenn Sie fertig sind, führen Sie Disconnect-MgGraph aus. Laut der Seite bleiben Sie so lange angemeldet, bis Sie das tun, da Token unter dem Standardbereich CurrentUser zwischengespeichert werden. Wenn die Anmeldung nur für die aktuelle Sitzung gelten soll, fügen Sie Connect-MgGraph den Parameter -ContextScope Process hinzu.
Erste Befehle für SharePoint-Websites
Die Referenz zu Get-MgSite listet die wichtigsten Parameter auf: -Filter, -Search, -Property (Alias -Select), -Top, -Sort und -All. Die Beispiele der Seite sind kurz:
Get-MgSitelistet Websites auf.Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"gibt nur Stamm-Websitesammlungen mit zwei Eigenschaften zurück.
Darauf können Sie aufbauen:
- Liste mit Paging. Führen Sie
Get-MgSite -Allaus, um jede Ergebnisseite abzurufen. Ohne-Allsehen Sie möglicherweise nur die erste Seite. - Spalten auswählen. Fügen Sie
-Property "id,displayName,webUrl"hinzu, damit die Ausgabe klein und übersichtlich bleibt. - Nach Stichwort suchen. Führen Sie
Get-MgSite -Search "finance"aus. Die Graph-Such-API gleicht Freitext über mehrere Websiteeigenschaften ab. - Eine Website abrufen. Führen Sie
Get-MgSite -SiteId <id>aus, wobei die ID der Wertidaus einem vorherigen Ergebnis ist. Sie hat die Form eines Hostnamens, gefolgt von zwei GUIDs, durch Kommas getrennt.
Jeder dieser Cmdlets entspricht einem REST-Aufruf. Get-MgSite -All liest die Sammlung sites unter https://graph.microsoft.com/v1.0/sites, der URL, die die REST-Dokumentation zum Auflisten von Websites zeigt. -Filter, -Search und -Property werden zu Abfrageoptionen für diese URL. Das SDK bezieht seine Token über die Microsoft Authentication Library (MSAL). Falls ein Cmdlet für einen benötigten Aufruf fehlt, kann Invoke-MgGraphRequest einen URI direkt aufrufen. Die Seite zur Fehlerbehebung verwendet diesen Befehl, um den URI hinter einem Fehler „Bad request“ zu prüfen.
Zwei Einschränkungen sind wichtig. Erstens gibt der Graph-Listenendpunkt Websites in der Standardgeografie der Organisation zurück. Für alle Geografien verweist Microsoft auf die API getAllSites, die dem Cmdlet Get-MgAllSite entspricht. Zweitens kann die Such-API nur nach createdDateTime sortieren.
Welche Berechtigungen benötigen Sie? Microsoft Graph PowerShell und SharePoint-Bereiche
Microsoft-Graph-Berechtigungen sind der Teil, der neue Anwender überrascht. Für das Lesen von Websites nennt die Cmdlet-Seite Sites.Read.All als die Option mit den geringsten Rechten und Sites.ReadWrite.All als die mit mehr Rechten. Wählen Sie die erste, es sei denn, ein Skript muss etwas ändern.
Sie müssen sich Bereichsnamen nicht merken. Zwei Hilfsbefehle übernehmen die Suche:
Find-MgGraphCommandzeigt, welche Berechtigungen ein Cmdlet oder eine API benötigt. Die Seite zur Problembehandlung verwendet als BeispielFind-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions.Find-MgGraphPermissionfindet Berechtigungen nach Bereich oder Name, zum BeispielFind-MgGraphPermission application. Die Ausgabe zeigt den Typ (delegiert oder Anwendung), ob eine Zustimmung durch einen Administrator erforderlich ist, und eine Beschreibung.
Beachten Sie einen Widerspruch in der Dokumentation. Die REST-Seite zum Auflisten von Websites zeigt für diesen Aufruf nur Anwendungsberechtigungen und kennzeichnet delegierten Zugriff als nicht unterstützt. Die Cmdlet-Seite zu Get-MgSite führt beide auf. Testen Sie Ihren eigenen Aufruf in einem Nicht-Produktionsmandanten und lesen Sie den Fehlertext, falls er fehlschlägt. Gehen Sie nicht davon aus, dass die Cmdlet-Seite für jeden Aufruf zutrifft.
Für unbeaufsichtigte Aufträge benötigen Sie einen App-only-Zugriff. Das bedeutet: eine App-Registrierung in Microsoft Entra, Anwendungsberechtigungen (auch API-Berechtigungen genannt) und die Zustimmung eines Administrators. Laut der Seite zur Problembehandlung erfordern Anwendungsberechtigungen die Zustimmung eines Administrators. Verwenden Sie ein Zertifikat oder eine verwaltete Identität statt eines eingegebenen Kennworts.
Beispiel: Eine Inventarliste veralteter Websites in fünf Befehlen
Die Zahlen in diesem Beispiel sind erfunden.
Ein Administrator möchte eine erste Liste der Websites, die seit einem Jahr niemand geändert hat.
Connect-MgGraph -Scopes "Sites.Read.All"$sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"$sites.Countliefert in diesem Beispiel 480.$old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }$old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation
Angenommen, die Datei enthält 60 Zeilen. Das sind 60 von 480 bzw. 12,5 %, eine überschaubare Liste, die Sie mit den Websitebesitzern durchgehen können. Der Administrator hat nur Leserechte und nichts geändert. Das Datum der letzten Änderung einer Website beweist nicht, dass niemand sie nutzt. Die Liste ist daher ein Ausgangspunkt für Rückfragen und keine Löschliste.
Häufige Fehler
- Anmeldung ohne Bereich. Eine Anmeldung ohne den passenden Bereich führt zu 403-Fehlern. Führen Sie
Get-MgContextaus und vergleichen Sie die Bereiche mit denen, die das Cmdlet benötigt. - Schreibbereiche für einen Leseauftrag anfordern.
Sites.ReadWrite.Allgeht über das hinaus, was ein Bericht braucht. Beginnen Sie mitSites.Read.All. - Vergessen von
-All. Ohne diesen Parameter kann eine Liste vollständig wirken, obwohl sie nur die erste Seite enthält. - Verwechslung der Modulversionen. Microsoft empfiehlt für Skripte das Modul v1.0. Das Beta-Modul befindet sich in der Vorschau und kann sich ohne Ankündigung ändern.
- Auslassen des Updates. Eine veraltete Version von
Microsoft.Graphgilt als dokumentierte Ursache für Versionskonflikte. Führen SieUpdate-Module Microsoft.Graphaus, bevor Sie andere Ursachen suchen. - Angemeldet bleiben auf einem gemeinsam genutzten Computer. Tokens werden zwischengespeichert. Führen Sie
Disconnect-MgGraphaus, wenn Sie fertig sind.
Wie Software helfen kann
Die meisten Anforderungen beim ersten Mal lassen sich mit Werkzeugen erfüllen, die Sie bereits besitzen. Das Microsoft Graph PowerShell SDK übernimmt Lesevorgänge und Exporte. Das SharePoint Admin Center zeigt Websitelisten und Einstellungen ohne Code. Excel oder Power BI wandelt eine CSV-Datei in einen Bericht um, den Websitebesitzer lesen können. Für geplante Ausführungen kann Azure Automation ein Skript mit einer verwalteten Identität ausführen.
Suchen Sie nach Lücken erst nach dem ersten Monat. Wenn Sie dasselbe Inventar immer wieder von Hand erstellen, reichen meist ein gespeichertes Skript mit einem festen Ausgabeordner und eine monatliche Erinnerung.
Nächster Schritt
Installieren Sie das SDK, führen Sie Connect-MgGraph -Scopes "Sites.Read.All" aus und exportieren Sie die Ausgabe von Get-MgSite -All noch heute in eine CSV-Datei. Verwenden Sie dann bei Ihrem nächsten Cmdlet Find-MgGraphCommand, um dessen Berechtigung zu ermitteln, bevor Sie Microsoft Graph PowerShell für SharePoint-Aufgaben produktiv einsetzen.