Get-EntraAgentUser

Модуль:
Microsoft.Entra.Users Module v1.3

Возвращает пользователя агента по идентификатору или перечисляет всех пользователей агента, подключенных к удостоверению агента.

Синтаксис

GetById (По умолчанию) 

Get-EntraAgentUser

    [-AgentUserId <String>]
    [<CommonParameters>]

GetByAgentId 

Get-EntraAgentUser

    -AgentId <String>
    [<CommonParameters>]

Описание

Командлет Get-EntraAgentUser извлекает пользователей агента из Microsoft Graph с помощью API версии 1.0. При использовании с ним возвращается -AgentUserIdодин пользователь агента. При использовании -AgentIdон возвращает всех пользователей агента, подключенных к указанному удостоверению агента. Если идентификатор пользователя агента не указан в наборе параметров GetById, он использует идентификатор пользователя хранимого агента из текущего сеанса или запрашивает его.

Примеры

Пример 1. Получение пользователя агента по идентификатору

Connect-Entra -Scopes 'User.Read.All'
Get-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

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

Пример 2. Получение пользователя агента из текущего сеанса

Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
New-EntraAgentUserForAgentId -DisplayName "My Agent User" -UserPrincipalName "myagent@contoso.onmicrosoft.com"
$agentUser = Get-EntraAgentUser
Write-Host "Agent User: $($agentUser.displayName)"

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

Пример 3. Вывод списка всех пользователей агента для удостоверения агента

Connect-Entra -Scopes 'User.Read.All'
$agentUsers = Get-EntraAgentUser -AgentId "cccccccc-3333-4444-5555-dddddddddddd"
$agentUsers | ForEach-Object { Write-Host "$($_.displayName) ($($_.userPrincipalName))" }

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

Пример 4. Получение пользователя агента с обработкой ошибок

Connect-Entra -Scopes 'User.Read.All'
try {
    $agentUser = Get-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    Write-Host "Agent User found: $($agentUser.displayName) ($($agentUser.userPrincipalName))"
} catch {
    Write-Host "Agent User not found or error occurred: $_"
}

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

Параметры

-AgentId

Идентификатор удостоверения агента для получения подключенных пользователей агента. Возвращает всех пользователей агента, подключенных к указанному удостоверению агента. Используется с набором параметров GetByAgentId.

Свойства параметров

Тип:System.String
Значение по умолчанию:None
Поддерживаются подстановочные знаки:False
DontShow:False

Наборы параметров

GetByAgentId
Position:Named
Обязательно:True
Значение из конвейера:False
Значение из конвейера по имени свойства:False
Значение из оставшихся аргументов:False

-AgentUserId

Идентификатор извлекаемого пользователя агента. Если он не указан, использует идентификатор пользователя хранимого агента из текущего сеанса или запрашивает его. Используется с набором параметров GetById.

Свойства параметров

Тип:System.String
Значение по умолчанию:None
Поддерживаются подстановочные знаки:False
DontShow:False

Наборы параметров

GetById
Position:Named
Обязательно:False
Значение из конвейера:False
Значение из конвейера по имени свойства:False
Значение из оставшихся аргументов:False

CommonParameters

Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.

Входные данные

None

Выходные данные

System.Object

При использовании -AgentUserIdвозвращает один объект агента User. При использовании -AgentIdвозвращает массив объектов пользователя агента. Каждый объект включает такие свойства, как id, displayName, userPrincipalName, mailNickname, accountEnabled и identityParentId.

Примечания

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

Для этого командлета требуются следующие разрешения Microsoft Graph:

  • User.Read.All