M365Con 2027 – bezpłatna konferencja online · 11–22 Jan 2027 · 120 sessions→ m365con.net

Blog · Mirko Peters

Microsoft Graph PowerShell dla administratorów SharePoint: pierwsze polecenia

By · · 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:

  1. Zainstaluj moduł na swoje konto: Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Użyj -Scope AllUsers tylko wtedy, gdy masz uprawnienia administratora i potrzebujesz wspólnej instalacji.
  2. Sprawdź wynik poleceniem Get-InstalledModule Microsoft.Graph.
  3. 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.Authentication jest instalowany razem z nimi.
  4. 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-MgSite wyś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:

  1. Lista ze stronicowaniem. Uruchom Get-MgSite -All, aby przejść przez wszystkie strony wyników. Bez -All zobaczysz tylko pierwszą stronę.
  2. Wybierz kolumny. Dodaj -Property "id,displayName,webUrl", aby wynik był mniejszy i czytelniejszy.
  3. Wyszukiwanie po słowie kluczowym. Uruchom Get-MgSite -Search "finance". Interfejs API wyszukiwania Graph dopasowuje tekst wolny do kilku właściwości witryny.
  4. Pobierz jedną witrynę. Uruchom Get-MgSite -SiteId <id>, gdzie identyfikator to wartość id z 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-MgGraphCommand pokazuje, jakie uprawnienia wymaga cmdlet lub interfejs API. Strona dotycząca rozwiązywania problemów używa jako przykładu polecenia Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions.
  • Find-MgGraphPermission wyszukuje uprawnienia według obszaru lub nazwy, na przykład Find-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.

  1. Connect-MgGraph -Scopes "Sites.Read.All"
  2. $sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"
  3. $sites.Count zwraca w tym przykładzie 480.
  4. $old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }
  5. $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-MgContext i porównaj zakresy z tymi, których wymaga cmdlet.
  • Żądanie zakresów zapisu w zadaniu odczytu. Sites.ReadWrite.All to więcej, niż potrzebuje raport. Zacznij od Sites.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.Graph jest wymieniona jako jedna z przyczyn konfliktów wersji. Zanim zaczniesz szukać innych przyczyn, uruchom Update-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.

Obserwuj podcastSpotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS