Get-EntraAgentUser

Módulo:
Microsoft.Entra.Users Module v1.3

Obtém um usuário do agente por sua ID ou lista todos os Usuários do Agente conectados a uma Identidade do Agente.

Sintaxe

GetById (Default) 

Get-EntraAgentUser

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

GetByAgentId 

Get-EntraAgentUser

    -AgentId <String>
    [<CommonParameters>]

Description

O Get-EntraAgentUser cmdlet recupera usuários do agente de Microsoft Graph usando a API v1.0. Quando usado com -AgentUserId, ele retorna um único usuário do agente. Quando usado com -AgentId, ele retorna todos os usuários do agente conectados à Identidade do Agente especificada. Se nenhuma ID de usuário do agente for fornecida no conjunto de parâmetros GetById, ela usará a ID de usuário do agente armazenado da sessão atual ou solicitará uma.

Exemplos

Exemplo 1: Obter um usuário do agente por ID

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

Este exemplo recupera o Usuário do Agente com a ID especificada.

Exemplo 2: Obter o usuário do agente da sessão atual

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)"

Este exemplo recupera o usuário do agente que foi criado na sessão atual usando a ID de usuário do agente armazenado.

Exemplo 3: listar todos os usuários do agente para uma identidade de agente

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

Este exemplo recupera todos os usuários do agente conectados à Identidade do Agente especificada.

Exemplo 4: Obter um usuário do agente com tratamento de erros

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: $_"
}

Este exemplo demonstra como recuperar um usuário do agente com tratamento de erro para capturar casos em que o usuário não existe.

Parâmetros

-AgentId

A ID da Identidade do Agente para a qual recuperar usuários do agente conectados. Retorna todos os usuários do agente conectados à identidade do agente especificada. Usado com o conjunto de parâmetros GetByAgentId.

Propriedades do parâmetro

Tipo:System.String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

GetByAgentId
Cargo:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-AgentUserId

A ID do usuário do agente a ser recuperado. Se não for fornecido, usará a ID de usuário do agente armazenado da sessão atual ou solicitará uma. Usado com o conjunto de parâmetros GetById.

Propriedades do parâmetro

Tipo:System.String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

GetById
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

None

Saídas

System.Object

Ao usar -AgentUserId, retorna um único objeto de Usuário do Agente. Ao usar -AgentId, retorna uma matriz de objetos do Usuário do Agente. Cada objeto inclui propriedades como id, displayName, userPrincipalName, mailNickname, accountEnabled e identityParentId.

Observações

Se a Identidade do Usuário ou do Agente do Agente com a ID especificada não for encontrada, o cmdlet gerará um erro. Ao listar pela Identidade do Agente, dá suporte à paginação para recuperar todos os resultados.

Esse cmdlet requer as seguintes permissões de Microsoft Graph:

  • User.Read.All