Microsoft Graph PowerShell для адміністраторів SharePoint: перші команди
By Mirko Peters · · Updated
Microsoft Graph PowerShell для SharePoint: встановіть SDK, увійдіть з потрібним дозволом, виведіть список сайтів за допомогою Get-MgSite і усуньте помилки 403, з якими адміністратори стикаються першими.
Automatically translated with AI from the original post. Read the English original
Microsoft Graph PowerShell для SharePoint означає використання Graph SDK для читання та керування сайтами з командного рядка. Ви встановлюєте один модуль, входите через Connect-MgGraph з областю дозволів і виконуєте командлети на кшталт Get-MgSite. Цей посібник призначений для адміністраторів SharePoint, які вже знають центр адміністрування SharePoint і хочуть безпечно почати роботу зі скриптами. Ви встановите SDK, увійдете з найменшою областю, яка працює, виведете список сайтів і навчитеся читати помилки, які з’являються першими.
Головне
- Microsoft Graph PowerShell — це SDK, що обгортає API Graph, тож кожній команді спочатку потрібен вхід через Connect-MgGraph з потрібними областями дозволів.
- Get-MgSite виводить список сайтів SharePoint і потребує щонайменше дозволу Sites.Read.All — це найменш привілейований варіант, який Microsoft документує для цієї команди.
- Get-MgContext показує, які області доступу має поточний сеанс, і це найшвидший спосіб пояснити помилку 403 Forbidden.
- Find-MgGraphCommand і Find-MgGraphPermission показують, який дозвіл потрібен команді, тож не доводиться вгадувати назви областей.
- Делегований вхід підходить людині за клавіатурою, тоді як вхід від імені застосунку з сертифікатом або керованою ідентичністю підходить для фонових завдань без участі користувача.
Що таке Microsoft Graph PowerShell і навіщо його використовують адміністратори
Microsoft Graph — це єдиний API для даних Microsoft 365: користувачі, групи, файли, пошта, Teams і сайти SharePoint. SDK Microsoft Graph PowerShell обгортає API Graph у командлети. Вам не потрібно писати веб-запити до кожної кінцевої точки. Ви виконуєте Get-MgSite і отримуєте назад об’єкти сайтів.
Для адміністратора SharePoint це дає три практичні переваги.
- Один інструмент для всіх служб. Той самий вхід працює для сайтів, користувачів і груп. Скрипт може вивести список сайтів, а потім знайти їхніх власників.
- Модель дозволів, яку можна прочитати. Кожен виклик потребує іменованих дозволів, які називаються областями. Ви можете побачити, які області має сеанс, і зрозуміти, чому виклик було відхилено.
- Шлях від застарілих модулів. Опис сутності Microsoft Graph PowerShell називає його заміною для виведених з експлуатації модулів Azure AD PowerShell і MSOnline.
Спільнотний модуль PnP PowerShell — інший поширений вибір для скриптів SharePoint, і його документація зазначає, що деякі командлети також звертаються до Graph. Graph PowerShell не замінює всі інструменти адміністратора SharePoint. Він охоплює те, що надає API Graph. Деякі параметри клієнта досі містяться в центрі адміністрування SharePoint або в інших модулях. Сприймайте Graph як один інструмент у наборі, а не єдиний.
Крок 1: встановіть SDK і увійдіть
У посібнику зі встановлення рекомендовано PowerShell 7 або новішу версію на всіх платформах. Windows PowerShell потребує версії 5.1 або новішої, .NET Framework 4.7.2 або новішої та політики виконання RemoteSigned або менш обмежувальної.
Виконайте такі кроки:
- Встановіть модуль для свого облікового запису:
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Використовуйте-Scope AllUsersлише тоді, коли маєте права адміністратора і потрібне спільне встановлення. - Перевірте результат командою
Get-InstalledModule Microsoft.Graph. - Майте на увазі, що основний модуль встановлює понад 47 підмодулів. На сторінці зазначено, що можна встановити лише ті, що вам потрібні, і що разом із ними постачається
Microsoft.Graph.Authentication. - Оновлюйте згодом командою
Update-Module Microsoft.Graph. Застарілий модуль згадується серед причин конфліктів версій.
Встановлення в одній версії PowerShell не встановлює модуль в іншій, тож виконуйте команду у тій версії, яку використовуватимете.
Тепер увійдіть. На сторінці про команди автентифікації пояснюється, що SDK підтримує два типи доступу: делегований і лише для застосунку. Делегований доступ діє від імені ввійшовшого користувача, а його дозволи задаються областями. Доступ лише для застосунку працює без користувача, з сертифікатом, клієнтським секретом або керованою ідентичністю.
Для перших команд використовуйте делегований доступ і запитуйте одну область лише для читання:
Connect-MgGraph -Scopes "Sites.Read.All"
Відкриється вікно браузера для входу. Щоб перевірити, що ви отримали, виконайте Get-MgContext | Select -ExpandProperty Scopes. Microsoft описує Get-MgContext як команду, що повертає відомості про поточний сеанс, зокрема ідентифікатор клієнта, ідентифікатор клієнта (tenant), області та тип автентифікації. Коли закінчите, виконайте Disconnect-MgGraph. На сторінці зазначено, що ви залишаєтеся ввійшовшими, доки цього не зробите, оскільки токени кешуються в області CurrentUser за замовчуванням. Додайте -ContextScope Process до Connect-MgGraph, якщо хочете, щоб вхід діяв лише в поточному сеансі.
Перші команди для сайтів SharePoint
Довідник Get-MgSite описує основні параметри: -Filter, -Search, -Property (псевдонім -Select), -Top, -Sort і -All. Приклади самої сторінки короткі:
Get-MgSiteвиводить список сайтів.Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"повертає лише кореневі колекції сайтів, з двома властивостями.
Далі можна рухатися так:
- Список зі сторінками. Виконайте
Get-MgSite -All, щоб переглянути всі сторінки результатів. Без-Allви можете побачити лише першу сторінку. - Оберіть стовпці. Додайте
-Property "id,displayName,webUrl", щоб вивід залишався компактним і читабельним. - Пошук за ключовим словом. Виконайте
Get-MgSite -Search "finance". API пошуку Graph знаходить вільний текст у кількох властивостях сайту. - Отримайте один сайт. Виконайте
Get-MgSite -SiteId <id>, де ідентифікатор — це значенняidз попереднього результату. Він має вигляд імені хоста, а далі два GUID, розділені комами.
Кожна з цих команд відповідає виклику REST. Get-MgSite -All читає колекцію сайтів за адресою https://graph.microsoft.com/v1.0/sites, яку REST-документація наводить для отримання списку сайтів, а -Filter, -Search і -Property стають параметрами запиту для цієї адреси. SDK отримує токени через Microsoft Authentication Library (MSAL). Якщо для потрібного виклику немає команди, Invoke-MgGraphRequest може викликати URI напряму. На сторінці з усуненням несправностей вона використовується для перевірки URI, що стоїть за помилкою Bad request.
Варто знати два обмеження. По-перше, кінцева точка списку Graph повертає сайти в географії організації за замовчуванням. Для всіх географій Microsoft пропонує API getAllSites, якому відповідає команда Get-MgAllSite. По-друге, API пошуку може сортувати лише за createdDateTime.
Які дозволи вам потрібні? Області Microsoft Graph PowerShell і SharePoint
Дозволи Microsoft Graph — це та частина, яка найчастіше дивує нових користувачів. Для читання сайтів сторінка з описом командлетів називає Sites.Read.All найменш привілейованим варіантом, а Sites.ReadWrite.All — привілейованішим. Беріть перший, якщо скрипт не має щось змінювати.
Запам'ятовувати назви областей доступу не обов'язково. Для пошуку є дві допоміжні команди:
Find-MgGraphCommandпоказує, які дозволи потрібні для командлета або API. На сторінці з усуненням несправностей як приклад використаноFind-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions.Find-MgGraphPermissionзнаходить дозволи за областю або назвою, наприкладFind-MgGraphPermission application. У результаті вказано тип (делегований чи застосунку), чи потрібна згода адміністратора, і опис.
Зверніть увагу на одну розбіжність у документації. Сторінка REST для отримання списку сайтів показує для цього виклику лише дозволи застосунку та позначає делегований доступ як непідтримуваний. Сторінка командлета Get-MgSite перелічує обидва варіанти. Перевірте свій виклик у непродуктивному клієнті та читайте текст помилки, якщо він не спрацьовує. Не вважайте, що сторінка командлета правильна для кожного виклику.
Для фонових завдань без участі людини потрібен доступ лише для застосунку. Це означає реєстрацію застосунку в Microsoft Entra, дозволи застосунку (їх також називають дозволами API) і згоду адміністратора. На сторінці з усуненням несправностей сказано, що дозволи застосунку вимагають згоди адміністратора. Використовуйте сертифікат або керовану ідентичність, а не пароль, введений вручну.
Приклад: інвентаризація застарілих сайтів у п'яти командах
Числа в цьому прикладі вигадані.
Адміністратор хоче отримати перший список сайтів, які ніхто не змінював протягом року.
Connect-MgGraph -Scopes "Sites.Read.All"$sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"$sites.Countповертає 480 у цьому прикладі.$old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }$old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation
Припустімо, що у файлі 60 рядків. Це 60 із 480, або 12,5 відсотка, — короткий список, який можна переглянути з власниками сайтів. Адміністратор має лише доступ для читання і нічого не змінив. Дата останньої зміни сайту не доводить, що ним ніхто не користується, тож список є відправною точкою для запитань, а не списком для видалення.
Типові помилки
- Підключення без потрібної області доступу. Вхід без потрібної області доступу призводить до помилок 403. Виконайте
Get-MgContextі порівняйте області доступу з тими, яких потребує командлет. - Запит прав на запис для завдання читання.
Sites.ReadWrite.Allдля звіту більш ніж достатньо. Почніть зSites.Read.All. - Забутий параметр
-All. Без нього список може здаватися повним, хоча це лише перша сторінка. - Плутанина з версіями модулів. Microsoft рекомендує для скриптів модуль v1.0. Бета-модуль перебуває у попередньому перегляді й може змінюватися без попередження.
- Пропущене оновлення. Застаріла версія
Microsoft.Graphє відомою причиною конфліктів версій. ВиконайтеUpdate-Module Microsoft.Graph, перш ніж шукати інші причини. - Залишена сесія на спільному комп'ютері. Токени кешуються. Коли закінчите, виконайте
Disconnect-MgGraph.
Як може допомогти програмне забезпечення
Більшість першочергових потреб закривають інструменти, які у вас уже є. Microsoft Graph PowerShell SDK відповідає за читання й експорт. Центр адміністрування SharePoint показує списки сайтів і налаштування без коду. Excel або Power BI перетворює CSV на звіт, який можуть прочитати власники сайтів. Для запланованих запусків Azure Automation може виконувати скрипт з керованою ідентичністю.
Шукайте прогалини лише після першого місяця. Якщо ви щоразу вручну відтворюєте одну й ту саму інвентаризацію, зазвичай достатньо збереженого скрипта з фіксованою папкою для результатів і щомісячного нагадування.
Наступний крок
Встановіть SDK, виконайте Connect-MgGraph -Scopes "Sites.Read.All" і сьогодні експортуйте результат Get-MgSite -All у CSV. Потім використовуйте Find-MgGraphCommand для кожного наступного командлета, щоб дізнатися його дозволи, перш ніж запускати Microsoft Graph PowerShell для завдань SharePoint уробочому середовищі.