New-EntraAgentUserForAgentId
Cria um novo Utilizador de Agente usando uma Identidade de Agente.
Sintaxe
Default (Predefinição)
New-EntraAgentUserForAgentId
-DisplayName <String>
[-UserPrincipalName <String>]
[-MailNickname <String>]
[-AgentIdentityId <String>]
[<CommonParameters>]
Descrição
O New-EntraAgentUserForAgentId cmdlet cria um novo Utilizador Agente ao publicar no endpoint dos utilizadores do Microsoft Graph usando um ID de Identidade de Agente como pai identidade. O mailNickname deriva por defeito do prefixo UserPrincipalname, mas pode ser sobreposto com o -MailNickname parâmetro ou de forma interativa. Se -UserPrincipalName não for fornecido, o cmdlet procura o domínio padrão do inquilino e solicita interativamente um UPN sugerido.
Exemplos
Exemplo 1: Criar um Utilizador Agente com todos os parâmetros
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 Utilizador Agente com o nome de exibição especificado e o nome principal do utilizador, usando a Identidade do Agente criada na sessão atual.
Exemplo 2: Criar um Utilizador Agente com prompts
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 Utilizador Agente. O cmdlet irá pedir o nome principal de utilizador se não for fornecido.
Exemplo 3: Crie múltiplos Utilizadores de Agente para a mesma Identidade de Agente
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 múltiplos Utilizadores de Agente associados à mesma Identidade de Agente.
Exemplo 4: Criar um Utilizador de Agente com ID de Identidade de Agente explícito
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 Utilizador Agente ao fornecer explicitamente o ID de Identidade do Agente, o que é útil ao ligar a partir de diferentes escopos de módulos ou scripts.
Parâmetros
-AgentIdentityId
O ID de Identidade do Agente para associar a este utilizador. Se não for fornecido, o cmdlet utiliza o valor armazenado do New-EntraAgentIDForAgentIdentityBlueprint. Use este parâmetro ao chamar a partir de diferentes escopos de módulos ou quando quiser especificar explicitamente a Identidade do Agente.
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-DisplayName
O nome de exibição do Utilizador Agente.
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Posto: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-MailNickname
O apelido de email (alias) para o Utilizador Agente. Se não for fornecido, deriva do prefixo UserPrincipalName (a parte antes do símbolo @) e o utilizador é solicitado a confirmá-lo ou a sobrepê-lo.
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-UserPrincipalName
O nome principal do utilizador (email) do Utilizador Agente (por exemplo, username@domain.onmicrosoft.com). Tem de ser um formato de endereço de email válido. Se não for fornecido, o cmdlet procura o domínio predefinido do inquilino e solicita interativamente um UPN sugerido derivado do nome de visualização.
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| 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
Devolve a resposta do objeto Agente User da Microsoft Graph API com as seguintes propriedades:
-
@odata.type —
microsoft.graph.agentUser - id — O identificador único do Utilizador Agente criado.
- displayName — O nome de exibição do Utilizador do Agente.
- UserPrincipalName — O nome principal do utilizador do Agente de Utilizador.
- mailNickname — O apelido de email (alias) do Utilizador Agente.
-
accountEnabled — Se a conta está ativada (sempre
true). - identityParentId — O ID da Identidade do Agente pai.
Propriedades adicionais da resposta da Graph API também podem ser incluídas.
Notas
Este cmdlet requer a seguinte permissão Microsoft Graph:
AgentIdUser.ReadWrite.All
O ID de Identidade do Agente pode ser fornecido através do -AgentIdentityId parâmetro ou é automaticamente recuperado da variável $global:EntraCurrentAgentIdentityId global definida por New-EntraAgentIDForAgentIdentityBlueprint. A variável global é usada porque este cmdlet está num módulo diferente (Microsoft.Entra.Users) dos cmdlets blueprint (Microsoft.Entra.Applications).
O cmdlet armazena o ID $script:CurrentAgentUserId de Utilizador do Agente criado para uso por cmdlets subsequentes.
O cmdlet inclui lógica de retentativa (até 10 tentativas com espera de 10 segundos) para lidar com atrasos de propagação.
Quando -UserPrincipalName não é fornecido, o cmdlet:
- Consulta ao domínio predefinido do inquilino através da API da organização
- Sugere um UPN ao concatenar as palavras do nome de exibição como prefixo com o domínio do inquilino
- Valida o UPN contra um padrão regex e volta a fazer o pedido se for inválido
O -UserPrincipalName parâmetro valida a entrada contra o padrão ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.