New-EntraAgentUserForAgentId
使用代理标识创建新的代理用户。
语法
Default (默认值)
New-EntraAgentUserForAgentId
-DisplayName <String>
[-UserPrincipalName <String>]
[-MailNickname <String>]
[-AgentIdentityId <String>]
[<CommonParameters>]
说明
该 New-EntraAgentUserForAgentId cmdlet 通过使用代理标识 ID 作为标识父级发布到Microsoft Graph用户终结点来创建新的代理用户。 mailNickname 默认派生自 UserPrincipalName 前缀,但可以通过参数或交互方式重写 -MailNickname 。 如果未 -UserPrincipalName 提供,cmdlet 将查找租户的默认域,并使用建议的 UPN 以交互方式提示。
示例
示例 1:创建包含所有参数的代理用户
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"
此示例使用在当前会话中创建的代理标识创建具有指定显示名称和用户主体名称的代理用户。
示例 2:使用提示创建代理用户
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"
此示例创建代理用户。 如果未提供,该 cmdlet 将提示输入用户主体名称。
示例 3:为同一代理标识创建多个代理用户
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"
此示例创建与同一代理标识关联的多个代理用户。
示例 4:使用显式代理标识 ID 创建代理用户
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
此示例通过显式提供代理标识 ID 来创建代理用户,这在从不同的模块范围或脚本调用时非常有用。
参数
-AgentIdentityId
要与此用户关联的代理标识 ID。 如果未提供,则 cmdlet 使用 New-EntraAgentIDForAgentIdentityBlueprint 中的存储值。 从不同的模块范围调用或想要显式指定代理标识时,请使用此参数。
参数属性
| 类型: | System.String |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值(按属性名称): | False |
| 来自剩余参数的值: | False |
-DisplayName
代理用户的显示名称。
参数属性
| 类型: | System.String |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | True |
| 来自管道的值: | False |
| 来自管道的值(按属性名称): | False |
| 来自剩余参数的值: | False |
-MailNickname
代理用户的邮件别名(别名)。 如果未提供,则派生自 UserPrincipalName 前缀(@符号前的部分),并提示用户确认或重写它。
参数属性
| 类型: | System.String |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值(按属性名称): | False |
| 来自剩余参数的值: | False |
-UserPrincipalName
代理用户的用户主体名称(例如, username@domain.onmicrosoft.com电子邮件)。 必须是有效的电子邮件地址格式。 如果未提供,该 cmdlet 会查找租户的默认域,并使用派生自显示名称的建议 UPN 以交互方式提示。
参数属性
| 类型: | System.String |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值(按属性名称): | False |
| 来自剩余参数的值: | False |
CommonParameters
此 cmdlet 支持通用参数:-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息,请参阅 about_CommonParameters。
输入
None
输出
System.Object
从Microsoft 图形 API响应中返回具有以下属性的 Agent User 对象:
-
@odata.type —
microsoft.graph.agentUser - id — 所创建的代理用户的唯一标识符。
- displayName — 代理用户的显示名称。
- userPrincipalName — 代理用户的用户主体名称。
- mailNickname — 代理用户的邮件昵称(别名)。
-
accountEnabled — 是否启用帐户(始终)。
true - identityParentId — 父代理标识的 ID。
还可以包含来自图形 API响应的其他属性。
备注
此 cmdlet 需要以下Microsoft Graph权限:
AgentIdUser.ReadWrite.All
代理标识 ID 可以通过参数提供-AgentIdentityId,也可以从设置的New-EntraAgentIDForAgentIdentityBlueprint全局变量$global:EntraCurrentAgentIdentityId中自动检索。 使用全局变量是因为此 cmdlet 与蓝图 cmdlet 位于不同的模块 (Microsoft.Entra.Users) 中。Microsoft.Entra.Applications
该 cmdlet 存储创建的代理用户 ID $script:CurrentAgentUserId 供后续 cmdlet 使用。
该 cmdlet 包括重试逻辑(最多 10 次尝试,等待 10 秒),以处理传播延迟。
-UserPrincipalName如果未提供,则 cmdlet:
- 通过组织 API 查询租户的默认域
- 通过将显示名称单词串联为租户域的前缀来建议 UPN
- 根据正则表达式模式验证 UPN,如果无效,则重新提示
参数 -UserPrincipalName 根据模式 ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$验证输入。