Как установить модуль Microsoft Graph в PowerShell

API Microsoft Graph позволяет нам взаимодействовать со всеми службами Microsoft через один источник. Для этого в PowerShell нам всегда приходилось устанавливать разные модули и устанавливать разные соединения. Теперь это не требуется благодаря модулю Microsoft Graph SDK для PowerShell.

Мы уже могли использовать Graph API с помощью вызовов Invoke-Webrequests, но это было не так просто. Новый модуль Microsoft Graph включает в себя множество командлетов, которые значительно упрощают взаимодействие с сервисами.

В этой статье я объясню, как установить модуль Microsoft Graph и как подключиться к нему с использованием различных разрешений.

SDK для PowerShell Microsoft Graph

Модуль Graph на самом деле называется Microsoft Graph PowerShell SDK и является оберткой для всех API Microsoft Graph. На данный момент он, похоже, только заменяет модуль Azure AD. Другие модули, которые мы используем для взаимодействия с Microsoft 365, на данный момент, похоже, не заменяются им.

30 июня 2022 года конечная точка Azure AD Graph будет устаревшей. Это означает, что вызовы, сделанные с помощью модуля Azure AD, больше не будут получать ответ. Поэтому важно переписать все ваши скрипты, использующие модуль Azure AD, на модуль Microsoft Graph.

Как упоминалось, Microsoft Graph PowerShell SDK позволяет нам взаимодействовать со всеми API от Microsoft. Это означает, что мы также можем использовать этот модуль для взаимодействия с SharePoint, Exchange Online, Compliance и т.д.

Еще одним преимуществом модуля является то, что он поддерживает PowerShell 7 и выше. Модуль Azure AD, например, не работает на PowerShell 7.

Установка модуля Microsoft Graph в PowerShell

На данный момент существует 38 модулей Microsoft Graph SDK. Мы можем установить их все сразу, но вам, возможно, стоит подумать о том, чтобы установить только те модули, которые вам действительно нужны.

Заметка

Убедитесь, что вы установили хотя бы модуль Microsoft.Graph.Authentication при установке отдельных модулей.

Вы можете просмотреть все доступные модули с помощью следующей команды:

Find-Module Microsoft.Graph*

Мы собираемся установить модуль Microsoft Graph только для текущего пользователя. Также возможно установить его для всех пользователей, но в этом случае вам нужно будет открыть PowerShell с повышенными привилегиями.

1. Откройте PowerShell или Windows Terminal

   - Щелкните правой кнопкой мыши на Пуск или нажмите клавишу Windows + X
   - Выберите Windows PowerShell или Windows Terminal (в Windows 11)
   

   

2. Установите SDK

   Введите следующую команду в PowerShell для установки модуля:
   
   Install-Module Microsoft.Graph -Scope CurrentUser
   

   

3. Принять ненадежный репозиторий

   Нажмите Y, чтобы установить из ненадежного репозитория
   

   

4. Подождите, пока установка завершится

   При установке всех модулей может потребоваться несколько минут, прежде чем установка будет завершена
   

   

Если вы хотите использовать бета-версию, вам нужно будет установить бета-модули отдельно:

Install-Module Microsoft.Graph.Beta -Scope CurrentUser

Подключение к Microsoft Graph из PowerShell

Есть две важные вещи при подключении к Microsoft Graph: вам нужно определить область применения, и существует бета-версия MgGraph. По умолчанию модуль будет использовать стабильную версию API. Однако новые функции сначала выпускаются в бета-версиях командлетов.

Другим важным шагом является то, что вам нужно будет указать области, которые вы хотите использовать. MgGraph предоставляет доступ ко всем API от Microsoft. Поэтому, когда вы хотите, например, экспортировать или просматривать пользователей Azure AD, вам необходимо только иметь разрешение User.Read.All.

Поиск областей Microsoft Graph

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

• Microsoft Graph Explorer
• Справочник по REST API Microsoft Graph
• cmdlet Find-MgGraphPermission

Microsoft Graph Explorer — это отличный инструмент для тестирования вызовов API к Microsoft Graph. Он содержит много примеров вызовов, чтобы помочь вам начать. Но он также укажет необходимые разрешения для вызова.

1. Откройте Graph Explorer
2. Выберите образец запроса слева
3. Нажмите на вкладку Изменить разрешения

Вам нужно будет выбрать по крайней мере одну из разрешений, упомянутых на вкладке 'Разрешения', при подключении к MS Graph в PowerShell.

Второй вариант - использовать справочник REST API. Вы можете выбрать в левом меню одну из сущностей, с которой хотите работать, а затем просмотреть необходимые разрешения. Вам не нужно добавлять все области, они перечислены от наименее к наиболее привилегированным.

Последний вариант — использовать cmdlet Find-MgGraphPermission или Find-MgGraphCommand. Оба cmdlet позволят вам искать требуемые разрешения для конкретного cmdlet MgGraph:

Find-MgGraphCommand -Command "Get-MgUserAuthenticationMethod" | select -ExpandProperty Permissions | Select -Unique name

Or 
Find-MgGraphPermission AuthenticationMethod

Подключение к MgGraph в PowerShell

Если вы знаете, какие области вам нужно использовать, вы можете подключиться к Microsoft Graph. Мы будем использовать обычный интерактивный метод, который отлично подходит для работы локально. Но когда вы хотите запланировать скрипты или использовать Microsoft Graph внутри Azure Runbook, вам нужно будет использовать один из других методов аутентификации.

Подключитесь к Microsoft Graph, например, с помощью областей User.Read.All и Group.ReadWrite.All:

Connect-MgGraph -Scopes "User.Read.All","Group.ReadWrite.All"

Вам нужно будет пройти аутентификацию и предоставить разрешения. Некоторые области требуют предоставления разрешений от имени вашей организации.

Теперь вы можете использовать Graph API. Когда вы работаете с Graph в PowerShell, вы можете добавить дополнительные разрешения к своей сессии, просто снова используя команду Connect-MsGraph с новыми разрешениями.

Если вы хотите использовать бета cmdlet, просто добавьте префикс бета перед именем ресурса cmdlet. Например, чтобы использовать бета cmdlet Get-MgUser, вы можете использовать Get-MgBetaUser.

Обновите модуль Microsoft Graph

Модуль Microsoft Graph все еще находится в разработке, и новые функции добавляются регулярно. Поэтому важно поддерживать ваш модуль в актуальном состоянии, чтобы вы могли использовать последние команды Graph в ваших скриптах PowerShell.

Чтобы обновить модуль, мы можем использовать командлет Update-Module в PowerShell, после чего указываем имя модуля:

Update-Module Microsoft.Graph

Заключение

Немного сложно найти правильные команды модуля Microsoft Graph SDK, но это замечательно, что один модуль позволяет взаимодействовать со всеми сервисами Microsoft. На момент написания документация все еще немного тонка, поэтому написание скриптов требует много проб и ошибок.

Надеюсь, эта статья помогла вам начать работу с модулем MgGraph. Если у вас есть какие-либо вопросы, просто оставьте комментарий ниже.