Get-EntraAgentUser

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

透過 ID 取得代理使用者，或列出所有與代理身份相關的代理使用者。

語法

GetById (預設值) 

Get-EntraAgentUser

    [-AgentUserId <String>]
    [<CommonParameters>]

GetByAgentId 

Get-EntraAgentUser

    -AgentId <String>
    [<CommonParameters>]

Description

該 Get-EntraAgentUser cmdlet 使用 v1.0 API 從 Microsoft Graph 取得代理使用者資料。 當與 -AgentUserId一起使用時，會回傳一個代理使用者。 當與 一起使用 -AgentId時，會回傳所有與指定代理身份相關的代理使用者。 如果 GetById 參數中沒有提供代理使用者 ID，則會使用目前會話中儲存的代理使用者 ID，或會提示該代理使用者。

範例

範例 1：依 ID 取得代理人使用者

Connect-Entra -Scopes 'User.Read.All'
Get-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

此範例取得具有指定 ID 的代理使用者。

範例 2：從當前會話取得代理使用者

Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
New-EntraAgentUserForAgentId -DisplayName "My Agent User" -UserPrincipalName "myagent@contoso.onmicrosoft.com"
$agentUser = Get-EntraAgentUser
Write-Host "Agent User: $($agentUser.displayName)"

此範例是利用儲存的代理使用者 ID 取得目前會話中建立的代理使用者。

範例 3：列出代理身份的所有代理使用者

Connect-Entra -Scopes 'User.Read.All'
$agentUsers = Get-EntraAgentUser -AgentId "cccccccc-3333-4444-5555-dddddddddddd"
$agentUsers | ForEach-Object { Write-Host "$($_.displayName) ($($_.userPrincipalName))" }

此範例會取得所有與指定代理身份相關的代理使用者。

範例 4：取得具備錯誤處理功能的代理使用者

Connect-Entra -Scopes 'User.Read.All'
try {
    $agentUser = Get-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    Write-Host "Agent User found: $($agentUser.displayName) ($($agentUser.userPrincipalName))"
} catch {
    Write-Host "Agent User not found or error occurred: $_"
}

此範例展示了如何利用錯誤處理來檢索代理使用者，以捕捉該使用者不存在的情況。

參數

-AgentId

agent 身份的 ID，用以取得已連接的 Agent 使用者。 回傳所有與指定代理身份相關的代理使用者。 搭配 GetByAgentId 參數設定使用。

參數屬性

類型:System.String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

GetByAgentId
Position:Named
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-AgentUserId

要取回的代理使用者 ID。 若未提供，則使用當前會話中儲存的代理使用者 ID，或提示代理。 搭配 GetById 參數設定使用。

參數屬性

類型:System.String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

GetById
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

使用 -AgentUserId時，會回傳一個單一的代理使用者物件。 使用 -AgentId時，會回傳一個代理使用者物件陣列。 每個物件包含 id、displayName、userPrincipalName、mailNickname、accountEnabled 及 identityParentId。

備註

若找不到具有指定 ID 的代理使用者或代理身份，指令本會拋出錯誤。 以代理身份排序時，支援分頁以取得所有結果。

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

  • User.Read.All