New-EntraAgentUserForAgentId

New-EntraAgentUserForAgentId

    -DisplayName <String>
    [-UserPrincipalName <String>]
    [-MailNickname <String>]
    [-AgentIdentityId <String>]
    [<CommonParameters>]

O New-EntraAgentUserForAgentId cmdlet cria um novo Usuário do Agente postando no ponto de extremidade Microsoft Graph usuários usando uma ID de Identidade do Agente como o pai da identidade. O mailNickname é derivado do prefixo UserPrincipalName por padrão, mas pode ser substituído pelo -MailNickname parâmetro ou interativamente. Se -UserPrincipalName não for fornecido, o cmdlet procurará o domínio padrão do locatário e solicitará interativamente com um UPN sugerido.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity" -SponsorUserIds @("user1@contoso.com")
New-EntraAgentUserForAgentId -DisplayName "Agent Identity 26192008" -UserPrincipalName "AgentIdentity26192008@contoso.onmicrosoft.com"

Este exemplo cria um Usuário do Agente com o nome de exibição e o nome de entidade de usuário especificados, usando a Identidade do Agente criada na sessão atual.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
# Assumes Agent Identity Blueprint and Agent Identity are already created
New-EntraAgentUserForAgentId -DisplayName "HR Agent User"

Este exemplo cria um usuário do agente. O cmdlet solicitará o nome da entidade de segurança do usuário se não for fornecido.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "Finance Blueprint" -SponsorUserIds @("finance-admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "Finance Agent" -SponsorUserIds @("finance-user@contoso.com")

# Create first Agent User
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 1" -UserPrincipalName "financeagent1@contoso.onmicrosoft.com"

# Create second Agent User for the same Agent Identity
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 2" -UserPrincipalName "financeagent2@contoso.onmicrosoft.com"

Este exemplo cria vários usuários de agente associados à mesma Identidade do Agente.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
$agentIdentity = New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity"
New-EntraAgentUserForAgentId -DisplayName "Agent User" -UserPrincipalName "agentuser@contoso.onmicrosoft.com" -AgentIdentityId $agentIdentity.id

Este exemplo cria um Usuário do Agente fornecendo explicitamente a ID de Identidade do Agente, que é útil ao chamar de escopos ou scripts de módulo diferentes.

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.

Retorna o objeto Agent User da resposta do Microsoft API do Graph com as seguintes propriedades:

• @odata.type — microsoft.graph.agentUser
• id — o identificador exclusivo do usuário do agente criado.
• displayName — O nome de exibição do Usuário do Agente.
• userPrincipalName — o nome principal do usuário do agente.
• mailNickname — O apelido de email (alias) do usuário do agente.
• accountEnabled – Se a conta está habilitada (sempre true).
• identityParentId — A ID da identidade do agente pai.

Propriedades adicionais da resposta API do Graph também podem ser incluídas.

Esse cmdlet requer a seguinte permissão de Microsoft Graph:

• AgentIdUser.ReadWrite.All

A ID de Identidade do Agente pode ser fornecida por meio do -AgentIdentityId parâmetro ou é recuperada automaticamente da variável $global:EntraCurrentAgentIdentityId global definida por New-EntraAgentIDForAgentIdentityBlueprint. A variável global é usada porque esse cmdlet está em um módulo diferente (Microsoft.Entra.Users) do que os cmdlets de blueprint (Microsoft.Entra.Applications).

O cmdlet armazena a ID $script:CurrentAgentUserId de Usuário do Agente criada para uso por cmdlets subsequentes.

O cmdlet inclui lógica de repetição (até 10 tentativas com esperas de 10 segundos) para lidar com atrasos de propagação.

Quando -UserPrincipalName não for fornecido, o cmdlet:

• Consulta o domínio padrão do locatário por meio da API da organização
• Sugere um UPN concatenando as palavras de nome de exibição como um prefixo com o domínio do locatário
• Valida o UPN em relação a um padrão regex e solicita novamente se inválido

O -UserPrincipalName parâmetro valida a entrada em relação ao padrão ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.