Создание сценариев PowerShell с помощью Microsoft Graph

Статья
Developer (Начальный уровень)
21 мин до завершения

В этом руководстве описано, как создать скрипт PowerShell, который использует API Microsoft Graph для доступа к данным от имени пользователя.

Примечание.

Сведения о том, как использовать Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений, см. в этом руководстве по проверке подлинности только для приложений.

В этом руководстве описан порядок выполнения перечисленных ниже задач.

Совет

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

Вы также можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.

Предварительные условия

Перед началом работы с этим руководством на компьютере разработки должен быть установлен PowerShell . PowerShell 5.1 является минимальным требованием, но рекомендуется использовать PowerShell 7.

У вас также должна быть рабочая или учебная учетная запись Майкрософт с почтовым ящиком Exchange Online. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Примечание.

Это руководство было написано с помощью PowerShell 7.2.2 и пакета SDK Для Microsoft Graph PowerShell версии 1.9.5. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.

Регистрация приложения на портале

Осталось 20 мин

В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности пользователей. Вы можете зарегистрировать приложение в Центре администрирования Microsoft Entra или с помощью пакета SDK Для Microsoft Graph PowerShell.

Регистрация приложения для проверки подлинности пользователей

В этом разделе описано, как зарегистрировать приложение, которое поддерживает проверку подлинности пользователей с помощью потока кода устройства.

Примечание.

Регистрация приложения для проверки подлинности пользователя в пакете SDK Для Microsoft Graph PowerShell необязательна. Пакет SDK имеет собственную регистрацию приложения и соответствующий идентификатор клиента. Однако использование собственного идентификатора приложения обеспечивает больший контроль над областями разрешений для определенного скрипта PowerShell.

Центр администрирования Microsoft Entra
PowerShell

Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите Новая регистрация. Введите имя приложения, например Graph User Auth Tutorial.

Задайте поддерживаемые типы учетных записей . Доступны следующие варианты:

Вариант	Кто может выполнить вход?
Учетные записи только в этом каталоге организации	Только пользователи в организации Microsoft 365
Учетные записи в любом каталоге организации	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи)
Учетные записи в любом каталоге организации... и личные учетные записи Майкрософт	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи) и личные учетные записи Майкрософт

Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и сохраните его. Оно понадобится на следующем шаге. Если вы выбрали Учетные записи в этом каталоге организации только для поддерживаемых типов учетных записей, скопируйте идентификатор каталога (клиента) и сохраните его.
Выберите пункт Проверка подлинности в разделе Управление. Найдите раздел Дополнительные параметры и установите переключатель Разрешить общедоступные клиентские потоки на Да, а затем нажмите кнопку Сохранить.

Чтобы использовать PowerShell, вам потребуется пакет SDK Для Microsoft Graph PowerShell. Если у вас его нет, инструкции по установке см. в разделе Установка пакета SDK Для Microsoft Graph PowerShell .

Важно!

Для сценария PowerShell требуется рабочая или учебная учетная запись с ролью администратора приложений, администратора облачных приложений или глобального администратора. Если ваша учетная запись имеет роль разработчика приложений, вы можете зарегистрироваться в Центре администрирования Microsoft Entra.

Создайте файл с именем RegisterAppForUserAuth.ps1 и добавьте следующий код.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Сохраните файл.
Откройте PowerShell и измените текущий каталог на расположение RegisterAppForUserAuth.ps1.

Выполните следующую команду, заменив <значение> аудитории нужным значением (см. таблицу ниже).

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth Tutorial" -SignInAudience <audience-value>

Значение SignInAudience	Кто может выполнить вход?
`AzureADMyOrg`	Только пользователи в организации Microsoft 365
`AzureADMultipleOrgs`	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи)
`AzureADandPersonalMicrosoftAccount`	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи) и личные учетные записи Майкрософт
`PersonalMicrosoftAccount`	Только личные учетные записи Майкрософт

Следуйте запросу, чтобы открыть https://microsoft.com/devicelogin в браузере, введите предоставленный код и завершите процесс проверки подлинности.
Скопируйте значения идентификатора клиента и проверки подлинности из выходных данных скрипта. Эти значения потребуются на следующем шаге.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Примечание.

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

Добавление проверки подлинности пользователя

Осталось 17 мин

В этом разделе вы выполните проверку подлинности сеанса PowerShell в качестве пользователя для Microsoft Graph. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph.

Пакет SDK Для Microsoft Graph PowerShell предоставляет два метода проверки подлинности для проверки подлинности пользователей: интерактивную проверку подлинности в браузере и коде устройства. Интерактивная проверка подлинности в браузере использует браузер устройства по умолчанию, чтобы разрешить пользователю войти в систему. Проверка подлинности кода устройства позволяет выполнять проверку подлинности в средах, в которых нет браузера по умолчанию. В этом упражнении будет использоваться проверка подлинности кода устройства.

Важно!

Если пакет SDK PowerShell для Microsoft Graph еще не установлен, установите его сейчас , прежде чем продолжить.

Проверка подлинности пользователя

Откройте PowerShell и используйте следующую команду, чтобы задать $clientID переменную сеанса, заменив <your-client-id> идентификатором клиента для регистрации приложения.
```
$clientId = <your-client-id>
```
Задайте переменную сеанса $tenantId . Если вы решили разрешить вход только пользователям в организации при регистрации приложения, замените <идентификатор клиента> идентификатором клиента своей организации. В противном случае замените на common.
```
$tenantId = <tenant-id>
```
Задайте переменную сеанса $graphScopes .
```
$graphScopes = "user.read mail.read mail.send"
```
Используйте следующую команду для проверки подлинности пользователя в текущем сеансе PowerShell.
```
# Authenticate the user
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -Scopes $graphScopes -UseDeviceAuthentication
```
Совет

Если вы предпочитаете использовать интерактивную проверку подлинности браузера, опустите -UseDeviceAuthentication параметр .
Откройте браузер и перейдите по url-адресу. Введите предоставленный код и войдите в систему.

Важно!

Помните о всех существующих учетных записях Microsoft 365, которые вошли в браузер при просмотре страницы https://microsoft.com/devicelogin. Используйте функции браузера, такие как профили, гостевой режим или частный режим, чтобы проверить подлинность в качестве учетной записи, которую вы планируете использовать для тестирования.

После завершения вернитесь в окно PowerShell. Выполните следующую команду, чтобы проверить контекст проверки подлинности.

# Get the Graph context
Get-MgContext

ClientId              : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
TenantId              : 601faea3-be45-4960-898f-92b379b17cd9
CertificateThumbprint :
Scopes                : {Mail.Read, Mail.Send, openid, profile…}
AuthType              : Delegated
AuthProviderType      : DeviceCodeProvider
CertificateName       :
Account               : MeganB@contoso.com
AppName               : PowerShell Graph Tutorial
ContextScope          : CurrentUser
Certificate           :
PSHostVersion         : 2022.4.1
ClientTimeout         : 00:05:00

Получение пользователя

Осталось 12 мин

В этом разделе вы получите пользователя, прошедшего проверку подлинности.

В сеансе PowerShell, прошедшем проверку подлинности, выполните следующую команду, чтобы получить текущий контекст. Контекст предоставляет сведения для идентификации пользователя, прошедшего проверку подлинности.
```
$context = Get-MgContext
```
Выполните следующую команду, чтобы получить пользователя из Microsoft Graph.
```
# Get the authenticated user by UPN
$user = Get-MgUser -UserId $context.Account -Select 'displayName, id, mail, userPrincipalName'
```
Совет

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

Выполните следующие команды, чтобы вывести сведения о пользователе.

Write-Host "Hello," $user.DisplayName
# For Work/school accounts, email is in Mail property
# Personal accounts, email is in UserPrincipalName
Write-Host "Email:", ($user.Mail ?? $user.UserPrincipalName)

Hello, Megan Bowen!
Email: MeganB@contoso.com

Описание кода

Рассмотрим команду, используемую для получения пользователя, прошедшего проверку подлинности. Это, казалось бы, простая команда, но есть некоторые ключевые детали, которые следует заметить.

Доступ к "мне"

Команда Get-MgUser создает запрос к API get user API. Этот API доступен двумя способами:

GET /me
GET /users/{user-id}

Пакет SDK Для Microsoft Graph PowerShell не поддерживает конечную точку GET /me API. Чтобы использовать конечную точку GEt /users/{user-id} , необходимо указать значение параметра {user-id} . В приведенном выше $context.Account примере используется значение . Это значение содержит имя участника-пользователя, прошедшего проверку подлинности.

Запрос определенных свойств

Функция использует -Select параметр команды для указания набора необходимых ей свойств. При этом параметр запроса $select добавляется в вызов API.

Строго типизированный тип возвращаемого значения

Функция возвращает объект, MicrosoftGraphUser десериализованный из ответа JSON из API. Так как команда использует -Select, только запрошенные свойства будут иметь значения в возвращаемом объекте. Все остальные свойства будут иметь значения по умолчанию.

Перечисление папки "Входящие"

Осталось 10 мин

В этом разделе вы получите список сообщений в почтовом ящике пользователя.

В сеансе PowerShell, прошедшем проверку подлинности, убедитесь, что задана $user переменная.
```
PS > $user.DisplayName
Megan Bowen
```

Выполните следующую команду, чтобы получить список папки "Входящие" пользователя.

Get-MgUserMailFolderMessage -UserId $user.Id -MailFolderId Inbox -Select `
  "from,isRead,receivedDateTime,subject" -OrderBy "receivedDateTime DESC" `
  -Top 25 | Format-Table Subject,@{n='From';e={$_.From.EmailAddress.Name}}, `
  IsRead,ReceivedDateTime

Просмотрите выходные данные.

Subject                                    From                    IsRead ReceivedDateTime
-------                                    ----                    ------ ----------------
Updates from Ask HR and other communities  Contoso Demo on Yammer  False  4/19/2022 10:19:02 PM
Employee Initiative Thoughts               Patti Fernandez         False  4/19/2022 3:15:56 PM
Voice Mail (11 seconds)                    Alex Wilber             False  4/18/2022 2:24:16 PM
Our Spring Blog Update                     Alex Wilber             True   4/18/2022 1:52:03 PM
Atlanta Flight Reservation                 Alex Wilber             False  4/13/2022 2:30:27 AM
Atlanta Trip Itinerary - down time         Alex Wilber             False  4/12/2022 4:46:01 PM

Описание кода

Рассмотрим команду, используемую для вывода списка папки "Входящие" пользователя.

Доступ к известным почтовым папкам

Команда Get-MgUserMailFolderMessage создает запрос к API перечисления сообщений , в частности с помощью конечной GET /users/{user-id}/mailFolders/{folder-id}/messages точки. При использовании этой конечной точки API возвращает только сообщения в запрошенной папке почты. В этом случае, так как папка "Входящие" является хорошо известной папкой по умолчанию внутри почтового ящика пользователя, она доступна по известному имени: -MailFolderId Inbox. Доступ к папкам, не используемым по умолчанию, можно получить таким же образом, заменив известное имя свойством идентификатора почтовой папки. Дополнительные сведения о доступных известных именах папок см. в разделе Тип ресурса mailFolder.

Доступ к коллекции

Get-MgUser В отличие от команды из предыдущего раздела, которая возвращает один объект, этот метод возвращает коллекцию сообщений. Большинство API в Microsoft Graph, возвращающих коллекцию, не возвращают все доступные результаты в одном ответе. Вместо этого они используют разбиение на страницы , чтобы вернуть часть результатов, предоставляя метод для клиентов, чтобы запросить следующую "страницу".

Размеры страниц по умолчанию

API, использующие разбиение на страницы, реализуют размер страницы по умолчанию. Для сообщений значение по умолчанию — 10. Клиенты могут запрашивать больше (или меньше) с помощью параметра запроса $top . В пакете SDK для Microsoft Graph PowerShell это выполняется с помощью -Top 25 параметра .

Примечание.

Значение, передаваемое через -Top , является верхней границей, а не явным числом. API возвращает количество сообщений до указанного значения.

Сортировка коллекций

Функция использует -OrderBy параметр в запросе для запроса результатов, отсортированных по времени получения сообщения (receivedDateTime свойство). Он включает ключевое DESC слово, чтобы сообщения, полученные в последнее время, отображались первыми. При этом параметр запроса $orderby добавляется в вызов API.

Отправка почты

Осталось 8 мин

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

В сеансе PowerShell, прошедшем проверку подлинности, убедитесь, что задана $user переменная.
```
PS > $user.DisplayName
Megan Bowen
```

Используйте следующую команду, чтобы определить объект, представляющий текст запроса для API отправки почты .

$sendMailParams = @{
    Message = @{
        Subject = "Testing Microsoft Graph"
        Body = @{
            ContentType = "text"
            Content = "Hello world!"
        }
        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = ($user.Mail ?? $user.UserPrincipalName)
                }
            }
        )
    }
}

Используйте следующую команду, чтобы отправить сообщение.
```
Send-MgUserMail -UserId $user.Id -BodyParameter $sendMailParams
```
Примечание.

Если вы тестируете с помощью клиента разработчика из Программы разработчика Microsoft 365, отправленное сообщение электронной почты может не быть доставлено, и вы можете получить отчет о недоставки. Если это случится с вами, обратитесь в службу поддержки через Центр администрирования Microsoft 365.
Чтобы убедиться, что сообщение получено, повторите Get-MgUserMailFolderMessage команду из предыдущего шага.

Описание кода

Рассмотрим команды, используемые для отправки сообщения.

Отправка почты

Команда Send-MgUserMail создает запрос к API отправки почты .

Создание объектов

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

Необязательно: добавление собственного кода

Осталось 5 мин

В этом разделе вы будете использовать собственные команды пакета SDK Для Microsoft Graph PowerShell. Это может быть фрагмент кода из документации Microsoft Graph или обозревателя Graph или созданный вами код. Этот раздел является необязательным.

Выбор API

Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров, приведенных в документации по API, настроить запрос API в Graph Explorer и использовать созданный фрагмент кода или использовать Find-MgGraphCommand команду для поиска соответствующей команды.

Например, одной из конечных точек API для создания события является POST /users/{id | userPrincipalName}/events. Его можно использовать для поиска соответствующей команды PowerShell.

PS > Find-MgGraphCommand -Uri "/users/{id | userPrincipalName}/events" -Method "POST"

   APIVersion: v1.0

Command         Module   Method URI                     OutputType           Permissions           Variants
-------         ------   ------ ---                     ----------           -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent {Calendars.ReadWrite} {Create1, CreateExp…

   APIVersion: beta

Command         Module   Method URI                     OutputType            Permissions           Variants
-------         ------   ------ ---                     ----------            -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent1 {Calendars.ReadWrite} {Create, CreateExp…

Выходные данные указывают, что New-MgUserEvent команда является соответствующей командой.

Настройка разрешений

Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают проверку подлинности пользователей (делегированная) или личные учетные записи Майкрософт, например.

Отключите текущий сеанс (Disconnect-MgGraph) и повторно подключитесь с необходимым разрешением в параметре -Scopes .

Совет

-ForceRefresh Использование параметра с командой Connect-MgGraph гарантирует, что будут применены только что настроенные разрешения.

Выполнение команды

Теперь, когда у вас есть необходимые разрешения, выполните выбранную команду.

Поделиться через

Создание сценариев PowerShell с помощью Microsoft Graph

Предварительные условия

Регистрация приложения на портале

Регистрация приложения для проверки подлинности пользователей

Добавление проверки подлинности пользователя

Проверка подлинности пользователя

Получение пользователя

Описание кода

Доступ к "мне"

Запрос определенных свойств

Строго типизированный тип возвращаемого значения

Перечисление папки "Входящие"

Описание кода

Доступ к известным почтовым папкам

Доступ к коллекции

Размеры страниц по умолчанию

Сортировка коллекций

Отправка почты

Описание кода

Отправка почты

Создание объектов

Необязательно: добавление собственного кода

Выбор API

Настройка разрешений

Выполнение команды

Поздравляем!