M365Con 2027 – бесплатная онлайн-конференция · 11–22 Jan 2027 · 120 sessions→ m365con.net

Блог · Mirko Peters

Microsoft Graph PowerShell для администраторов SharePoint: первые команды

By · · 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 или менее строгую.

Выполните следующие шаги:

  1. Установите модуль для своей учётной записи: Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Используйте -Scope AllUsers, только если у вас есть права администратора и нужна общая установка.
  2. Проверьте результат командой Get-InstalledModule Microsoft.Graph.
  3. Имейте в виду, что основной модуль устанавливает более 47 подмодулей. На странице сказано, что можно установить только нужные, и что Microsoft.Graph.Authentication устанавливается вместе с ними.
  4. Обновить модуль позже можно командой Update-Module Microsoft.Graph. Устаревший модуль указан как одна из причин конфликтов версий.

Установка в одной версии PowerShell не устанавливает модуль в другой, поэтому выполняйте команду в той версии, которую будете использовать.

Теперь выполните вход. На странице о командах аутентификации объясняется, что SDK поддерживает два типа доступа: делегированный и только для приложения. Делегированный доступ действует от имени вошедшего пользователя, а его разрешения задаются областями (scopes). Доступ только для приложения работает без пользователя, с помощью сертификата, клиентского секрета или управляемого удостоверения.

Для первых команд используйте делегированный доступ и запросите одну область только для чтения:

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

Откроется окно браузера для входа. Чтобы проверить, что вы получили, выполните Get-MgContext | Select -ExpandProperty Scopes. Microsoft описывает Get-MgContext как команду, которая возвращает сведения о текущем сеансе, например идентификатор клиента, идентификатор клиента Microsoft Entra, области и тип аутентификации. По окончании выполните 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" возвращает только корневые коллекции сайтов, с двумя свойствами.

Дальше можно двигаться так:

  1. Список с постраничным выводом. Выполните Get-MgSite -All, чтобы получить все страницы результатов. Без -All может отобразиться только первая страница.
  2. Выбор столбцов. Добавьте -Property "id,displayName,webUrl", чтобы вывод был компактным и читаемым.
  3. Поиск по ключевому слову. Выполните Get-MgSite -Search "finance". API поиска Graph сопоставляет свободный текст с несколькими свойствами сайта.
  4. Получение одного сайта. Выполните 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) и согласие администратора. На странице по устранению неполадок сказано, что разрешения приложения требуют согласия администратора. Используйте сертификат или управляемое удостоверение, а не пароль, введённый вручную.

Пример: инвентаризация неактивных сайтов в пять команд

Числа в этом примере выдуманы.

Администратору нужен первый список сайтов, которые никто не менял в течение года.

  1. Connect-MgGraph -Scopes "Sites.Read.All"
  2. $sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"
  3. В этом примере $sites.Count возвращает 480.
  4. $old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }
  5. $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, чтобы узнать его разрешения, прежде чем запускать задачи SharePoint через Microsoft Graph PowerShell в производственной среде.

Подписаться на подкастSpotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS