New-EntraAgentUserForAgentId

模組:
Microsoft.Entra.Users Module v1.3

使用代理身份建立新的代理使用者。

語法

Default (預設值) 

New-EntraAgentUserForAgentId

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

Description

該 New-EntraAgentUserForAgentId cmdlet 透過以代理身份 ID 作為身份父，向 Microsoft Graph 使用者端點發布資料，建立新的代理使用者。 mailNickname 預設源自 UserPrincipalName 前綴，但可以透過參數 -MailNickname 或互動式覆蓋。 如果 -UserPrincipalName 沒有提供，指令檔會查詢租戶的預設網域，並以互動式提示建議的 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"

此範例創建代理使用者。 如果沒有提供，指令長會提示使用者主體名稱。

範例 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

與此使用者關聯的代理身份識別碼。 若未提供，指令小程式將使用 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）。 電子郵件地址格式必須有效。 若未提供，指令檔會查詢租戶的預設網域，並互動式提示由顯示名稱衍生的建議 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 回應的代理使用者物件，並具備以下屬性：

  • @odata.類型 — microsoft.graph.agentUser
  • id — 所建立代理使用者的唯一識別碼。
  • displayName — 代理使用者的顯示名稱。
  • userPrincipalName — 代理使用者的使用者主體名稱。
  • mailNickname — 代理使用者的郵件暱稱（別名）。
  • accountEnabled — 帳戶是否啟用（始終 true）。
  • identityParentId — 父代理身份的識別碼。

也可以包含來自 圖形 API 回應的其他屬性。

備註

此指令小程式需要以下 Microsoft Graph 權限：

  • AgentIdUser.ReadWrite.All

代理身份識別碼可透過-AgentIdentityId參數提供，或自動從由 設定New-EntraAgentIDForAgentIdentityBlueprint的全域變數$global:EntraCurrentAgentIdentityId取得。 使用全域變數是因為此指令檔位於與藍圖指令匣Microsoft.Entra.Applications（）不同的模組Microsoft.Entra.Users（）。

該 cmdlet 會儲存已建立的 Agent User ID $script:CurrentAgentUserId ，供後續 cmdlet 使用。

指令小程式包含重試邏輯（最多 10 次嘗試，等待 10 秒）以處理傳播延遲。

若 -UserPrincipalName 未提供，則指令長：

  • 透過組織 API 查詢租戶的預設網域
  • 透過將顯示名稱詞串接為租戶網域的前綴，建議 UPN
  • 驗證 UPN 是否符合正則表達式模式，若無效則重新提示

參數 -UserPrincipalName 會根據模式 ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$驗證輸入。