New-EntraAgentUserForAgentId

New-EntraAgentUserForAgentId

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

New-EntraAgentUserForAgentId コマンドレットは、エージェント ID を ID の親として使用して、Microsoft Graph ユーザー エンドポイントに投稿することで、新しいエージェント ユーザーを作成します。 mailNickname は、既定では UserPrincipalName プレフィックスから派生していますが、 -MailNickname パラメーターでオーバーライドすることも、対話形式でオーバーライドすることもできます。 -UserPrincipalNameが指定されていない場合、コマンドレットはテナントの既定のドメインを検索し、推奨される UPN を使用して対話形式でプロンプトを表示します。

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"

この例では、現在のセッションで作成されたエージェント ID を使用して、指定した表示名とユーザー プリンシパル名を持つエージェント ユーザーを作成します。

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"

この例では、エージェント ユーザーを作成します。 指定されていない場合、コマンドレットはユーザー プリンシパル名の入力を求めます。

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"

この例では、同じエージェント 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 を明示的に指定してエージェント ユーザーを作成します。これは、さまざまなモジュール スコープまたはスクリプトから呼び出すときに便利です。

このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。 詳細については、about_CommonParametersを参照してください。

次のプロパティを使用して、Microsoft Graph API 応答から Agent User オブジェクトを返します。

• @odata.type — microsoft.graph.agentUser
• id — 作成されたエージェント ユーザーの一意識別子。
• displayName — エージェント ユーザーの表示名。
• userPrincipalName — エージェント ユーザーのユーザー プリンシパル名。
• mailNickname — エージェント ユーザーのメール ニックネーム (エイリアス)。
• accountEnabled — アカウントが有効になっているかどうか (常に true)。
• identityParentId — 親エージェント ID の ID。

Graph API応答からの追加のプロパティも含まれる場合があります。

このコマンドレットには、次のMicrosoft Graphアクセス許可が必要です。

• AgentIdUser.ReadWrite.All

エージェント ID は、-AgentIdentityId パラメーターを使用して指定することも、New-EntraAgentIDForAgentIdentityBlueprintによって設定$global:EntraCurrentAgentIdentityIdグローバル変数から自動的に取得することもできます。 このコマンドレットはブループリント コマンドレット (Microsoft.Entra.Applications) とは異なるモジュール (Microsoft.Entra.Users) にあるため、グローバル変数が使用されます。

このコマンドレットは、作成されたエージェント ユーザー ID を後続のコマンドレットで使用するために $script:CurrentAgentUserId に格納します。

このコマンドレットには、伝達遅延を処理するための再試行ロジック (最大 10 回の試行と 10 秒の待機) が含まれています。

-UserPrincipalNameが指定されていない場合、コマンドレットは次のようになります。

• 組織 API を使用してテナントの既定のドメインにクエリを実行する
• 表示名の単語をプレフィックスとしてテナント ドメインと連結して UPN を提案する
• 正規表現パターンに対して UPN を検証し、無効な場合は再プロンプトを表示します

-UserPrincipalName パラメーターは、パターン ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$に対して入力を検証します。