New-EntraAgentUserForAgentId
Создает нового пользователя агента с помощью удостоверения агента.
Синтаксис
Default (По умолчанию)
New-EntraAgentUserForAgentId
-DisplayName <String>
[-UserPrincipalName <String>]
[-MailNickname <String>]
[-AgentIdentityId <String>]
[<CommonParameters>]
Описание
Командлет New-EntraAgentUserForAgentId создает нового пользователя агента, публикуя в конечную точку Microsoft Graph пользователей с помощью идентификатора агента в качестве родительского удостоверения. MailNickname является производным от префикса UserPrincipalName по умолчанию, но может быть переопределен параметром -MailNickname или интерактивным образом. Если -UserPrincipalName это не указано, командлет ищет домен клиента по умолчанию и запрашивает интерактивное имя участника-пользователя с помощью предлагаемого имени участника-пользователя.
Примеры
Пример 1. Создание пользователя агента со всеми параметрами
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity" -SponsorUserIds @("user1@contoso.com")
New-EntraAgentUserForAgentId -DisplayName "Agent Identity 26192008" -UserPrincipalName "AgentIdentity26192008@contoso.onmicrosoft.com"
В этом примере создается пользователь агента с указанным отображаемым именем и именем субъекта-пользователя, используя удостоверение агента, созданное в текущем сеансе.
Пример 2. Создание пользователя агента с запросами
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
# Assumes Agent Identity Blueprint and Agent Identity are already created
New-EntraAgentUserForAgentId -DisplayName "HR Agent User"
В этом примере создается пользователь агента. Командлет будет запрашивать имя участника-пользователя, если оно не указано.
Пример 3. Создание нескольких пользователей агента для одного удостоверения агента
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "Finance Blueprint" -SponsorUserIds @("finance-admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "Finance Agent" -SponsorUserIds @("finance-user@contoso.com")
# Create first Agent User
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 1" -UserPrincipalName "financeagent1@contoso.onmicrosoft.com"
# Create second Agent User for the same Agent Identity
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 2" -UserPrincipalName "financeagent2@contoso.onmicrosoft.com"
В этом примере создается несколько пользователей агента, связанных с тем же удостоверением агента.
Пример 4. Создание пользователя агента с явным идентификатором удостоверения агента
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
$agentIdentity = New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity"
New-EntraAgentUserForAgentId -DisplayName "Agent User" -UserPrincipalName "agentuser@contoso.onmicrosoft.com" -AgentIdentityId $agentIdentity.id
В этом примере создается пользователь агента, явно предоставляя идентификатор удостоверения агента, который полезен при вызове из разных областей модуля или скриптов.
Параметры
-AgentIdentityId
Идентификатор удостоверения агента, связанный с этим пользователем. Если этот параметр не указан, командлет использует сохраненное значение из New-EntraAgentIDForAgentIdentityBlueprint. Используйте этот параметр при вызове из разных областей модуля или при явном указании удостоверения агента.
Свойства параметров
| Тип: | System.String |
| Значение по умолчанию: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-DisplayName
Отображаемое имя пользователя агента.
Свойства параметров
| Тип: | System.String |
| Значение по умолчанию: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | True |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-MailNickname
Псевдоним почты (псевдоним) для пользователя агента. Если он не указан, он является производным от префикса UserPrincipalName (часть перед символом @), и пользователю будет предложено подтвердить или переопределить его.
Свойства параметров
| Тип: | System.String |
| Значение по умолчанию: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-UserPrincipalName
Имя участника-пользователя (электронная почта) для пользователя агента (например, username@domain.onmicrosoft.com). Должен быть допустимым форматом адреса электронной почты. Если это не указано, командлет ищет домен клиента по умолчанию и запрашивает интерактивное имя участника-пользователя, полученное от отображаемого имени.
Свойства параметров
| Тип: | System.String |
| Значение по умолчанию: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
CommonParameters
Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.
Входные данные
None
Выходные данные
System.Object
Возвращает объект user agent из ответа Microsoft API Graph со следующими свойствами:
-
@odata.type —
microsoft.graph.agentUser - id — уникальный идентификатор созданного пользователя агента.
- displayName — отображаемое имя пользователя агента.
- userPrincipalName — имя участника-пользователя агента.
- mailNickname — псевдоним почты (псевдоним) пользователя агента.
-
accountEnabled — включена ли учетная запись (всегда
true). - identityParentId — идентификатор родительского удостоверения агента.
Также могут быть включены дополнительные свойства из ответа API Graph.
Примечания
Для этого командлета требуется следующее Microsoft Graph разрешение:
AgentIdUser.ReadWrite.All
Идентификатор удостоверения агента может быть предоставлен с помощью -AgentIdentityId параметра или автоматически извлекается из глобальной переменной$global:EntraCurrentAgentIdentityId, заданной.New-EntraAgentIDForAgentIdentityBlueprint Глобальная переменная используется, так как этот командлет находится в другом модуле (Microsoft.Entra.Users), отличном от командлетов схемы (Microsoft.Entra.Applications).
Командлет сохраняет созданный идентификатор $script:CurrentAgentUserId пользователя агента для использования последующими командлетами.
Командлет включает логику повторных попыток (до 10 попыток с 10-секундными ожиданиями) для обработки задержек распространения.
Если -UserPrincipalName этот командлет не указан, выполните следующие действия.
- Запрашивает домен клиента по умолчанию через API организации
- Предлагает имя участника-пользователя путем объединения слов отображаемого имени в качестве префикса с доменом клиента
- Проверяет имя участника-пользователя в шаблоне regex и повторно запрашивает, если это недопустимо.
Параметр -UserPrincipalName проверяет входные данные в шаблоне ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.