Microsoft Graph PowerShell dla administratorów SharePoint: pierwsze polecenia
By Mirko Peters · · Updated
Microsoft Graph PowerShell dla SharePoint: zainstaluj zestaw SDK, zaloguj się z odpowiednim zakresem, wyświetl witryny poleceniem Get-MgSite i napraw błędy 403, z którymi administratorzy spotykają się najczęściej.
Automatically translated with AI from the original post. Read the English original
Microsoft Graph PowerShell dla SharePoint oznacza używanie zestawu SDK Graph do odczytu i zarządzania witrynami z poziomu wiersza poleceń. Instalujesz jeden moduł, logujesz się poleceniem Connect-MgGraph z zakresem uprawnień i uruchamiasz polecenia cmdlet, takie jak Get-MgSite. Ten przewodnik jest przeznaczony dla administratorów SharePoint, którzy znają already centrum administracyjne SharePoint i chcą bezpiecznie zacząć przygodę ze skryptami. Zainstalujesz zestaw SDK, zalogujesz się z najmniejszym działającym zakresem, wyświetlisz witryny i nauczysz się odczytywać błędy, które pojawiają się najpierw.
Najważniejsze wnioski
- Microsoft Graph PowerShell to zestaw SDK opakowujący interfejsy API Graph, dlatego każde polecenie wymaga wcześniej logowania poleceniem Connect-MgGraph z odpowiednimi zakresami uprawnień.
- Get-MgSite wyświetla witryny SharePoint i wymaga co najmniej uprawnienia Sites.Read.All, czyli najmniej uprzywilejowanej opcji udokumentowanej przez firmę Microsoft dla tego polecenia.
- Get-MgContext pokazuje, jakie zakresy posiada bieżąca sesja, i jest najszybszym sposobem wyjaśnienia błędu 403 Forbidden.
- Find-MgGraphCommand i Find-MgGraphPermission wskazują, jakie uprawnienie wymaga dane polecenie, dzięki czemu nie musisz zgadywać nazw zakresów.
- Logowanie delegowane sprawdza się, gdy przy klawiaturze siedzi człowiek, a logowanie aplikacji (tylko aplikacja) z certyfikatem lub tożsamością zarządzaną sprawdza się w zadaniach działających bez nadzoru.
Czym jest Microsoft Graph PowerShell i po co administratorzy z niego korzystają
Microsoft Graph to jednolity interfejs API dla danych Microsoft 365: użytkowników, grup, plików, poczty, usługi Teams i witryn SharePoint. Zestaw SDK Microsoft Graph PowerShell opakowuje interfejs API Graph w polecenia cmdlet. Nie piszesz żądań sieciowych do każdego endpointu. Uruchamiasz Get-MgSite i otrzymujesz z powrotem obiekty witryn.
Dla administratora SharePoint wynikają z tego trzy praktyczne korzyści.
- Jedno narzędzie dla wielu usług. Ta sama sesja logowania działa dla witryn, użytkowników i grup. Skrypt może wyświetlić witryny, a następnie sprawdzić ich właścicieli.
- Model uprawnień, który da się odczytać. Każde wywołanie wymaga nazwanych uprawnień, zwanych zakresami. Możesz sprawdzić, jakie zakresy ma sesja i dlaczego wywołanie zostało odrzucone.
- Droga od starszych modułów. Opis encji Microsoft Graph PowerShell określa go jako następcę wycofanych modułów Azure AD PowerShell i MSOnline.
Społecznościowy moduł PnP PowerShell to drugi popularny wybór do skryptów SharePoint, a jego dokumentacja zaznacza, że niektóre polecenia również komunikują się z Graph. Graph PowerShell nie zastępuje wszystkich narzędzi administracyjnych SharePoint. Obejmuje to, co udostępnia interfejs API Graph. Niektóre ustawienia dzierżawy nadal znajdują się w centrum administracyjnym SharePoint lub w innych modułach. Traktuj Graph jako jedno z narzędzi w swoim zestawie, a nie jedyne.
Krok 1: zainstaluj zestaw SDK i zaloguj się
Przewodnik instalacji zaleca PowerShell 7 lub nowszy na wszystkich platformach. Windows PowerShell wymaga wersji 5.1 lub nowszej, .NET Framework 4.7.2 lub nowszego oraz zasad wykonywania ustawionych na RemoteSigned lub mniej restrykcyjnych.
Wykonaj następujące kroki:
- Zainstaluj moduł na swoje konto:
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Użyj-Scope AllUserstylko wtedy, gdy masz uprawnienia administratora i potrzebujesz wspólnej instalacji. - Sprawdź wynik poleceniem
Get-InstalledModule Microsoft.Graph. - Pamiętaj, że główny moduł instaluje ponad 47 podmodułów. Strona podaje, że możesz zainstalować tylko te, których potrzebujesz, a
Microsoft.Graph.Authenticationjest instalowany razem z nimi. - Później zaktualizuj moduł poleceniem
Update-Module Microsoft.Graph. Nieaktualny moduł jest wymieniany jako jedna z przyczyn konfliktów wersji.
Instalacja w jednej wersji PowerShell nie instaluje modułu w drugiej, dlatego uruchom polecenie w tej wersji, której będziesz używać.
Teraz się zaloguj. Strona o poleceniach uwierzytelniania wyjaśnia, że SDK obsługuje dwa typy dostępu: delegowany i tylko aplikacyjny. Dostęp delegowany działa w imieniu zalogowanego użytkownika, a jego uprawnienia to zakresy. Dostęp tylko aplikacyjny działa bez użytkownika, z certyfikatem, kluczem tajnym klienta lub tożsamością zarządzaną.
Do pierwszych poleceń użyj dostępu delegowanego i poproś o jeden zakres tylko do odczytu:
Connect-MgGraph -Scopes "Sites.Read.All"
Otworzy się okno przeglądarki do zalogowania. Aby sprawdzić, co otrzymałeś, uruchom Get-MgContext | Select -ExpandProperty Scopes. Microsoft opisuje Get-MgContext jako polecenie zwracające szczegóły bieżącej sesji, takie jak identyfikator klienta, identyfikator dzierżawy, zakresy i typ uwierzytelniania. Po zakończeniu uruchom Disconnect-MgGraph. Strona podaje, że pozostajesz zalogowany, dopóki tego nie zrobisz, ponieważ tokeny są buforowane w domyślnym zakresie CurrentUser. Dodaj -ContextScope Process do Connect-MgGraph, jeśli chcesz, aby logowanie obowiązywało tylko w bieżącej sesji.
Pierwsze polecenia dla witryn SharePoint
Dokumentacja Get-MgSite opisuje główne parametry: -Filter, -Search, -Property (alias -Select), -Top, -Sort i -All. Przykłady na stronie są krótkie:
Get-MgSitewyświetla witryny.Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"zwraca tylko główne kolekcje witryn, z dwiema właściwościami.
Rozbuduj to stopniowo:
- Lista ze stronicowaniem. Uruchom
Get-MgSite -All, aby przejść przez wszystkie strony wyników. Bez-Allzobaczysz tylko pierwszą stronę. - Wybierz kolumny. Dodaj
-Property "id,displayName,webUrl", aby wynik był mniejszy i czytelniejszy. - Wyszukiwanie po słowie kluczowym. Uruchom
Get-MgSite -Search "finance". Interfejs API wyszukiwania Graph dopasowuje tekst wolny do kilku właściwości witryny. - Pobierz jedną witrynę. Uruchom
Get-MgSite -SiteId <id>, gdzie identyfikator to wartośćidz poprzedniego wyniku. Ma postać nazwy hosta, a następnie dwóch identyfikatorów GUID oddzielonych przecinkami.
Każde z tych poleceń odpowiada wywołaniu REST. Get-MgSite -All odczytuje kolekcję witryn pod adresem https://graph.microsoft.com/v1.0/sites, który dokumentacja REST podaje do pobierania witryn, a -Filter, -Search i -Property stają się opcjami zapytania w tym adresie URL. SDK pobiera tokeny za pośrednictwem biblioteki Microsoft Authentication Library (MSAL). Jeśli brakuje polecenia dla potrzebnego wywołania, Invoke-MgGraphRequest może wywołać URI bezpośrednio. Strona rozwiązywania problemów używa go, aby sprawdzić URI stojący za błędem Bad request.
Są dwa ważne ograniczenia. Po pierwsze, endpoint listy Graph zwraca witryny w domyślnym regionie geograficznym organizacji. Dla wszystkich regionów Microsoft wskazuje API getAllSites, które odpowiada poleceniu Get-MgAllSite. Po drugie, API wyszukiwania może sortować tylko według createdDateTime.
Jakich uprawnień potrzebujesz? Microsoft Graph PowerShell i zakresy SharePoint
Uprawnienia Microsoft Graph to element, który najbardziej zaskakuje nowych użytkowników. W przypadku odczytu witryn strona z opisem cmdletu wymienia Sites.Read.All jako wybór z najmniejszym zakresem uprawnień, a Sites.ReadWrite.All jako wybór z większym zakresem. Wybierz pierwsze, chyba że skrypt musi coś zmieniać.
Nie musisz pamiętać nazw zakresów. Do wyszukiwania służą dwa polecenia pomocnicze:
Find-MgGraphCommandpokazuje, jakie uprawnienia wymaga cmdlet lub interfejs API. Strona dotycząca rozwiązywania problemów używa jako przykładu poleceniaFind-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions.Find-MgGraphPermissionwyszukuje uprawnienia według obszaru lub nazwy, na przykładFind-MgGraphPermission application. Wynik pokazuje typ (delegowane lub aplikacyjne), to, czy zgodę wymaga administrator, oraz opis.
Warto zwrócić uwagę na jedną rozbieżność w dokumentacji. Strona REST dotycząca pobierania witryn pokazuje dla tego wywołania wyłącznie uprawnienia aplikacyjne i oznacza dostęp delegowany jako nieobsługiwany. Strona cmdletu Get-MgSite wymienia oba typy. Przetestuj własne wywołanie w dzierżawie niebędącej środowiskiem produkcyjnym i przeczytaj treść błędu, jeśli wywołanie się nie powiedzie. Nie zakładaj, że strona cmdletu jest poprawna dla każdego wywołania.
Zadania wykonywane bez nadzoru wymagają dostępu tylko aplikacyjnego. Oznacza to rejestrację aplikacji w Microsoft Entra, uprawnienia aplikacyjne (zwane także uprawnieniami interfejsu API) oraz zgodę administratora. Strona dotycząca rozwiązywania problemów mówi, że uprawnienia aplikacyjne wymagają zgody administratora. Używaj certyfikatu lub tożsamości zarządzanej, a nie wpisywanego hasła.
Przykład: lista nieaktywnych witryn w pięciu poleceniach
Liczby w tym przykładzie są zmyślone.
Administrator chce otrzymać pierwszą listę witryn, których nikt nie zmieniał od roku.
Connect-MgGraph -Scopes "Sites.Read.All"$sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"$sites.Countzwraca w tym przykładzie 480.$old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }$old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation
Załóżmy, że plik zawiera 60 wierszy. To 60 z 480, czyli 12,5 procent, a więc krótka lista do przejrzenia z właścicielami witryn. Administrator ma wyłącznie dostęp do odczytu i niczego nie zmienił. Data ostatniej modyfikacji witryny nie dowodzi, że nikt z niej nie korzysta, dlatego lista jest punktem wyjścia do zadawania pytań, a nie listą do usunięcia.
Częste błędy
- Logowanie bez zakresu. Logowanie bez odpowiedniego zakresu prowadzi do błędów 403. Uruchom
Get-MgContexti porównaj zakresy z tymi, których wymaga cmdlet. - Żądanie zakresów zapisu w zadaniu odczytu.
Sites.ReadWrite.Allto więcej, niż potrzebuje raport. Zacznij odSites.Read.All. - Pominięcie
-All. Bez tego parametru lista może wyglądać na kompletną, mimo że zawiera tylko pierwszą stronę. - Pomylenie wersji modułów. Microsoft zaleca do skryptów moduł v1.0. Moduł beta jest w wersji zapoznawczej i może zmienić się bez ostrzeżenia.
- Brak aktualizacji. Nieaktualna wersja
Microsoft.Graphjest wymieniona jako jedna z przyczyn konfliktów wersji. Zanim zaczniesz szukać innych przyczyn, uruchomUpdate-Module Microsoft.Graph. - Pozostawanie zalogowanym na współdzielonym komputerze. Tokeny są buforowane. Po zakończeniu pracy uruchom
Disconnect-MgGraph.
Jak oprogramowanie może pomóc
Większość potrzeb przy pierwszym kontakcie z tematem zaspokoją narzędzia, które już masz. Zestaw Microsoft Graph PowerShell SDK obsługuje odczyty i eksporty. Centrum administracyjne SharePoint pokazuje listy witryn i ich ustawienia bez kodu. Excel lub Power BI zamienia plik CSV w raport, który właściciele witryn mogą czytać. Do cyklicznych uruchomień usługa Azure Automation może wykonać skrypt z użyciem tożsamości zarządzanej.
Szukaj luk dopiero po upływie pierwszego miesiąca. Jeśli ciągle odtwarzasz ten sam spis ręcznie, zapisany skrypt z ustalonym folderem wyjściowym i miesięcznym przypomnieniem zwykle wystarczy.
Następny krok
Zainstaluj zestaw SDK, uruchom Connect-MgGraph -Scopes "Sites.Read.All" i wyeksportuj wynik Get-MgSite -All do pliku CSV już dziś. Następnie przed uruchomieniem zadań Microsoft Graph PowerShell dla SharePoint na środowisku produkcyjnym użyj Find-MgGraphCommand przy kolejnym cmdlecie, aby poznać wymagane dla niego uprawnienie.