Get-EntraAgentIdentity

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

透過 ID 取得代理身份，或列出代理身份藍圖中的所有代理身份。

語法

GetById (預設值) 

Get-EntraAgentIdentity

    -AgentId <String>
    [<CommonParameters>]

GetByBlueprint 

Get-EntraAgentIdentity

    [-AgentIdentityBlueprintId <String>]
    [<CommonParameters>]

Description

指令Get-EntraAgentIdentity小程式會從 Microsoft Graph 取得代理身份。 當與 一起使用 -AgentId時，會回傳一個單一代理身份。 當與 一起使用 -AgentIdentityBlueprintId時，會回傳所有指定藍圖子節點的代理身份。 若沒有提供藍圖 ID，則使用當前會話中儲存的藍圖 ID，或提示藍圖。

範例

範例 1：透過 ID 取得代理人身份

Connect-Entra -Scopes 'Application.Read.All'
Get-EntraAgentIdentity -AgentId "27a3cf14-5bdc-4814-bb13-8f1740ca9a4f"

此範例取得具有指定 ID 的代理身份。

範例 2：列出藍圖中的所有代理人身份

Connect-Entra -Scopes 'Application.Read.All'
$agents = Get-EntraAgentIdentity -AgentIdentityBlueprintId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
$agents | ForEach-Object { Write-Host "$($_.displayName) ($($_.id))" }

此範例可檢索所有指定代理身份藍圖的代理身份子體。

範例 3：目前會話藍圖的代理身份列表

Connect-Entra -Scopes 'Application.Read.All'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
$agents = Get-EntraAgentIdentity -AgentIdentityBlueprintId
$agents | ForEach-Object { Write-Host "$($_.displayName)" }

此範例列出了目前工作階段中使用儲存藍圖 ID 所建立的所有藍圖代理身份。

範例 4：取得帶有錯誤處理功能的代理身份

Connect-Entra -Scopes 'Application.Read.All'
try {
    $agent = Get-EntraAgentIdentity -AgentId "27a3cf14-5bdc-4814-bb13-8f1740ca9a4f"
    Write-Host "Agent found: $($agent.displayName)"
} catch {
    Write-Host "Agent not found or error occurred: $_"
}

此範例示範如何利用錯誤處理取得代理身份，以捕捉代理不存在的情況。

參數

-AgentId

要取得的特工身份ID。 搭配 GetById 參數設定使用。

參數屬性

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

參數集

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

-AgentIdentityBlueprintId

代理人身份藍圖的 ID，用來列出子代理人身份。 如果沒有提供，則使用目前會話中儲存的藍圖 ID，或是針對藍圖提供提示。 搭配 GetByBlueprint 參數設定使用。

參數屬性

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

參數集

GetByBlueprint
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

使用 -AgentId時，會回傳一個代理身份物件。 使用 -AgentIdentityBlueprintId時，會回傳一個代理身份物件陣列。 每個物件包含 id、displayName、appId 和 servicePrincipalType 等屬性。

備註

若找不到包含指定 ID 的代理身份或藍圖，指令長會拋出錯誤。 以藍圖列出時，支援分頁以取得所有結果。

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

  • Application.Read.All