Remove-EntraAgentIdentity

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

Exclui uma identidade de agente por sua ID ou exclui todas as Identidades do Agente (e seus Usuários do Agente) associadas a um Blueprint de Identidade do Agente.

Sintaxe

ByAgentId (Default) 

Remove-EntraAgentIdentity

    -AgentId <String>
    [-Force]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

ByBlueprintId 

Remove-EntraAgentIdentity

    -AgentIdentityBlueprintId <String>
    [-Force]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

O Remove-EntraAgentIdentity cmdlet exclui identidades do agente de Microsoft Entra usando a API v1.0. Quando usado com -AgentId, ele exclui uma única Identidade do Agente e todos os Usuários do Agente associados. Quando usado com -AgentIdentityBlueprintId, ele pesquisa todas as Identidades do Agente para o blueprint e exclui cada uma delas junto com seus Usuários do Agente associados.

O cmdlet requer confirmação antes de excluir, a menos que a opção -Force seja usada. Use -WhatIf para visualizar quais recursos seriam excluídos sem realmente executar a exclusão.

Exemplos

Exemplo 1: excluir uma identidade de agente por ID

Connect-Entra -Scopes 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentIdentity -AgentId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Force

Este exemplo exclui a Identidade do Agente e todos os Usuários do Agente associados.

Exemplo 2: excluir todas as identidades do agente para um blueprint

Connect-Entra -Scopes 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentIdentity -AgentIdentityBlueprintId "cccccccc-3333-4444-5555-dddddddddddd" -Force

Este exemplo pesquisa todas as Identidades do Agente associadas ao Blueprint especificado, exclui os usuários do agente e exclui as próprias identidades do agente.

Exemplo 3: exclusão de visualização com WhatIf

Connect-Entra -Scopes 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentIdentity -AgentIdentityBlueprintId "cccccccc-3333-4444-5555-dddddddddddd" -WhatIf

Este exemplo mostra quais Identidades do Agente e Usuários do Agente seriam excluídos sem executar a exclusão.

Exemplo 4: Excluir com tratamento de erros

Connect-Entra -Scopes 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
try {
    $result = Remove-EntraAgentIdentity -AgentId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Force
    Write-Host "Deleted Agent Identity: $($result.DisplayName)"
    Write-Host "Also deleted $($result.DeletedAgentUsers.Count) Agent User(s)"
} catch {
    Write-Host "Failed to delete: $_"
}

Este exemplo demonstra como excluir uma Identidade do Agente com tratamento de erros e inspecionar os Usuários do Agente excluídos.

Parâmetros

-AgentId

A ID da Identidade do Agente a ser excluída. O cmdlet também excluirá todos os Usuários do Agente associados a essa Identidade do Agente. Usado com o conjunto de parâmetros ByAgentId.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-AgentIdentityBlueprintId

A ID do Blueprint de Identidade do Agente. Todas as identidades de agente associadas a esse blueprint serão excluídas, juntamente com seus Usuários do Agente. Usado com o conjunto de parâmetros ByBlueprintId.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-Confirm

Solicita sua confirmação antes de executar o cmdlet.

Propriedades do parâmetro

Tipo:System.Management.Automation.SwitchParameter
Valor padrão:True
Dá suporte a curingas:False
DontShow:False
Aliases:cf

Conjuntos de parâmetros

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

-Force

Suprime o prompt de confirmação antes da exclusão.

Propriedades do parâmetro

Tipo:System.Management.Automation.SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

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

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Propriedades do parâmetro

Tipo:System.Management.Automation.SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False
Aliases:wi

Conjuntos de parâmetros

(All)
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.Collections.Hashtable

Retorna um hashtable (ou matriz de hashtables ao usar -AgentIdentityBlueprintId) com propriedades: Id, DisplayName, AgentIdentityBlueprintId, DeletedAgentUsers (matriz de informações de usuário excluídas) e Status.

Observações

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

  • AgentIdentity.DeleteRestore.All
  • AgentIdUser.ReadWrite.All

O cmdlet requer uma conexão Microsoft Entra ativa. Use Connect-Entra com os escopos acima para se conectar primeiro.

Ao excluir uma identidade de agente, todos os usuários do agente associados são excluídos primeiro. Se a exclusão do usuário do Agente falhar, o erro será registrado, mas a exclusão da Identidade do Agente ainda continuará.

Ao usar -AgentIdentityBlueprintId, o cmdlet dá suporte à paginação para lidar com blueprints com muitas Identidades do Agente.