New-EntraAgentUserForAgentId
Vytvoří nového uživatele agenta pomocí identity agenta.
Syntax
Default (Výchozí)
New-EntraAgentUserForAgentId
-DisplayName <String>
[-UserPrincipalName <String>]
[-MailNickname <String>]
[-AgentIdentityId <String>]
[<CommonParameters>]
Description
Rutina New-EntraAgentUserForAgentId vytvoří nového uživatele agenta publikováním koncového bodu uživatele Microsoft Graph pomocí ID identity agenta jako nadřazené identity identity. MailNickname je odvozen z předpony UserPrincipalName ve výchozím nastavení, ale lze je přepsat pomocí parametru -MailNickname nebo interaktivně. Pokud -UserPrincipalName není k dispozici, rutina vyhledá výchozí doménu tenanta a interaktivně zobrazí výzvu s navrhovaným hlavním názvem uživatele (UPN).
Příklady
Příklad 1: Vytvoření uživatele agenta se všemi parametry
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"
Tento příklad vytvoří uživatele agenta se zadaným zobrazovaným názvem a hlavním názvem uživatele pomocí identity agenta vytvořeného v aktuální relaci.
Příklad 2: Vytvoření uživatele agenta s výzvami
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"
Tento příklad vytvoří uživatele agenta. Pokud není zadaný, rutina zobrazí výzvu k zadání hlavního názvu uživatele.
Příklad 3: Vytvoření více uživatelů agenta pro stejnou identitu agenta
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"
Tento příklad vytvoří více uživatelů agenta přidružených ke stejné identitě agenta.
Příklad 4: Vytvoření uživatele agenta s explicitním ID identity agenta
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
Tento příklad vytvoří uživatele agenta tím, že explicitně zadá ID identity agenta, což je užitečné při volání z různých oborů modulů nebo skriptů.
Parametry
-AgentIdentityId
ID identity agenta, které se má přidružit k tomuto uživateli. Pokud není k dispozici, rutina použije uloženou hodnotu z New-EntraAgentIDForAgentIdentityBlueprint. Tento parametr použijte při volání z různých oborů modulů nebo při explicitním zadání identity agenta.
Vlastnosti parametru
| Typ: | System.String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-DisplayName
Zobrazovaný název uživatele agenta.
Vlastnosti parametru
| Typ: | System.String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | True |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-MailNickname
Poštovní přezdívka (alias) pro uživatele agenta. Pokud není zadaný, je odvozen z předpony UserPrincipalName (část před symbolem @) a uživatel se zobrazí výzva k potvrzení nebo přepsání.
Vlastnosti parametru
| Typ: | System.String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-UserPrincipalName
Hlavní název uživatele (e-mail) pro uživatele agenta (např username@domain.onmicrosoft.com. ). Musí to být platný formát e-mailové adresy. Pokud není zadaný, rutina vyhledá výchozí doménu tenanta a interaktivně zobrazí výzvu s navrhovaným upN odvozeným ze zobrazovaného názvu uživatele.
Vlastnosti parametru
| Typ: | System.String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
CommonParameters
Tato rutina podporuje běžné parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction a -WarningVariable. Další informace najdete v about_CommonParameters.
Vstupy
None
Výstupy
System.Object
Vrátí objekt Uživatele agenta z odpovědi Microsoft Graph API s následujícími vlastnostmi:
-
@odata.type —
microsoft.graph.agentUser - id – jedinečný identifikátor vytvořeného uživatele agenta.
- displayName – zobrazovaný název uživatele agenta.
- userPrincipalName – hlavní název uživatele agenta.
- mailNickname — Poštovní přezdívka (alias) uživatele agenta.
-
accountEnabled – určuje, jestli je účet povolený (vždy
true). - identityParentId – ID nadřazené identity agenta.
Mohou být zahrnuty i další vlastnosti z odpovědi Graph API.
Poznámky
Tato rutina vyžaduje následující oprávnění Microsoft Graph:
AgentIdUser.ReadWrite.All
ID identity agenta lze poskytnout prostřednictvím parametru -AgentIdentityId nebo se automaticky načte z globální proměnné $global:EntraCurrentAgentIdentityId nastavené parametrem New-EntraAgentIDForAgentIdentityBlueprint. Globální proměnná se používá, protože tato rutina je v jiném modulu (Microsoft.Entra.Users) než v rutinách podrobného plánu (Microsoft.Entra.Applications).
Rutina uloží vytvořené ID $script:CurrentAgentUserId uživatele agenta pro použití následujícími rutinami.
Rutina obsahuje logiku opakování (až 10 pokusů s 10sekundovými čekáními), která zpracovává zpoždění šíření.
Pokud -UserPrincipalName není k dispozici, rutina:
- Dotazuje výchozí doménu tenanta prostřednictvím rozhraní API organizace.
- Navrhne hlavní název uživatele (UPN) zřetězením zobrazovaného názvu jako předpony s doménou tenanta.
- Ověří hlavní název uživatele (UPN) vůči vzoru regulárního výrazu a znovu zobrazí výzvu, pokud je neplatný.
Parametr -UserPrincipalName ověřuje vstup proti vzoru ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.