Get-EntraAgentUser

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

Obtém um Utilizador Agente pelo seu ID, ou lista todos os Utilizadores Agentes ligados a uma Identidade de Agente.

Sintaxe

GetById (Predefinição) 

Get-EntraAgentUser

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

GetByAgentId 

Get-EntraAgentUser

    -AgentId <String>
    [<CommonParameters>]

Descrição

O Get-EntraAgentUser cmdlet recupera os Utilizadores Agentes do Microsoft Graph usando a API v1.0. Quando usado com -AgentUserId, devolve um único utilizador agente. Quando usado com -AgentId, devolve todos os utilizadores agentes ligados à Identidade do Agente especificada. Se não for fornecido o ID de utilizador do agente no conjunto de parâmetros GetById, utiliza o ID de utilizador do agente armazenado da sessão atual ou dos prompts para um.

Exemplos

Exemplo 1: Obter um Utilizador Agente por ID

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

Este exemplo recupera o Utilizador Agente com o ID especificado.

Exemplo 2: Obter o Utilizador 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 Utilizador Agente criado na sessão atual usando o ID de utilizador do agente armazenado.

Exemplo 3: Liste todos os Utilizadores de Agentes 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 Utilizadores do Agente que estão ligados à Identidade do Agente especificada.

Exemplo 4: Arranja um Utilizador 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 Utilizador Agente com tratamento de erros para detetar casos onde o utilizador não existe.

Parâmetros

-AgentId

O ID da Identidade do Agente para recuperar os Utilizadores do Agente conectados. Devolve todos os utilizadores de agentes que estão ligados à identidade de agente especificada. Usado com o conjunto de parâmetros GetByAgentId.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

GetByAgentId
Posto:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-AgentUserId

O ID do Utilizador Agente a recuperar. Se não for fornecido, usa o ID de utilizador do agente armazenado da sessão atual ou os pedidos para um. Usado com o conjunto de parâmetros GetById.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

GetById
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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, devolve um único objeto Agent User. Ao usar -AgentId, devolve um array de objetos Agente Utilizador. Cada objeto inclui propriedades como id, displayName, userPrincipalname, mailNickname, accountEnabled e identityParentId.

Notas

Se o Utilizador do Agente ou a Identidade do Agente com o ID especificado não forem encontrados, o cmdlet gerará um erro. Ao listar por Identidade do Agente, suporta paginação para obter todos os resultados.

Este cmdlet requer as seguintes permissões do Microsoft Graph:

  • Utilizador.Read.All