Get-EntraAgentIdentity

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

Obtém uma Identidade de Agente pelo seu ID, ou lista todas as Identidades de Agentes para um Blueprint de Identidade de Agente.

Sintaxe

GetById (Predefinição) 

Get-EntraAgentIdentity

    -AgentId <String>
    [<CommonParameters>]

GetByBlueprint 

Get-EntraAgentIdentity

    [-AgentIdentityBlueprintId <String>]
    [<CommonParameters>]

Descrição

O Get-EntraAgentIdentity cmdlet recupera uma Identidade de Agente a partir do Microsoft Graph. Quando usado com -AgentId, devolve uma identidade de agente único. Quando usado com -AgentIdentityBlueprintId, devolve todas as identidades dos agentes que são filhos do blueprint especificado. Se não for fornecido o ID do blueprint, usa o ID do blueprint armazenado da sessão atual ou os prompts para um.

Exemplos

Exemplo 1: Obtenha uma Identidade de Agente por ID

Connect-Entra -Scopes 'Application.Read.All'
Get-EntraAgentIdentity -AgentId "27a3cf14-5bdc-4814-bb13-8f1740ca9a4f"

Este exemplo recupera a Identidade do Agente com o ID especificado.

Exemplo 2: Liste todas as Identidades de Agentes para um Blueprint

Connect-Entra -Scopes 'Application.Read.All'
$agents = Get-EntraAgentIdentity -AgentIdentityBlueprintId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
$agents | ForEach-Object { Write-Host "$($_.displayName) ($($_.id))" }

Este exemplo recupera todas as Identidades de Agente que são filhos do Blueprint de Identidade de Agente especificado.

Exemplo 3: Listar Identidades de Agentes para o Blueprint da sessão atual

Connect-Entra -Scopes 'Application.Read.All'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
$agents = Get-EntraAgentIdentity -AgentIdentityBlueprintId
$agents | ForEach-Object { Write-Host "$($_.displayName)" }

Este exemplo lista todas as Identidades de Agente para o blueprint criado na sessão atual usando o ID do blueprint armazenado.

Exemplo 4: Obtenha uma Identidade de Agente com tratamento de erros

Connect-Entra -Scopes 'Application.Read.All'
try {
    $agent = Get-EntraAgentIdentity -AgentId "27a3cf14-5bdc-4814-bb13-8f1740ca9a4f"
    Write-Host "Agent found: $($agent.displayName)"
} catch {
    Write-Host "Agent not found or error occurred: $_"
}

Este exemplo demonstra como recuperar uma Identidade de Agente com tratamento de erros para detetar casos onde o agente não existe.

Parâmetros

-AgentId

O ID da Identidade do Agente a recuperar. 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:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-AgentIdentityBlueprintId

O ID do Plano de Identidade do Agente para listar as identidades dos agentes filhos. Se não for fornecido, usa o ID do blueprint armazenado da sessão atual ou os prompts para um. Usado com o conjunto de parâmetros GetByBlueprint.

Propriedades dos parâmetros

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

Conjuntos de parâmetros

GetByBlueprint
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 -AgentId, devolve um único objeto de Identidade do Agente. Ao usar -AgentIdentityBlueprintId, devolve um array de objetos Identidade do Agente. Cada objeto inclui propriedades como id, displayName, appId e servicePrincipalType.

Notas

Se a Identidade do Agente ou o Blueprint com o ID especificado não for encontrado, o cmdlet irá gerar um erro. Ao listar por blueprint, suporta a paginação para recuperar todos os resultados.

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

  • Application.Read.All