New-EntraAgentIDForAgentIdentityBlueprint

New-EntraAgentIDForAgentIdentityBlueprint

    -DisplayName <String>
    [-SponsorUserIds <String[]>]
    [-SponsorGroupIds <String[]>]
    [-OwnerUserIds <String[]>]
    [-AgentIdentityBlueprintId <String>]
    [<CommonParameters>]

New-EntraAgentIDForAgentIdentityBlueprint コマンドレットは、指定または格納されているエージェント ID と指定されたスポンサー/所有者を使用して、Microsoft Graph v1.0 AgentIdentity エンドポイントに投稿することで、新しいエージェント ID を作成します。 少なくとも 1 つのスポンサー (ユーザーまたはグループ) が必要です。 所有者は省略可能です。 AgentIdentityBlueprintId パラメーターが指定されていない場合、コマンドレットは以前のNew-EntraAgentIdentityBlueprint呼び出しから格納されたブループリント ID を使用します。 格納されている ID が存在しない場合、コマンドレットは対話形式でプロンプトを表示します。 スポンサーまたは所有者がパラメーターとして指定されていない場合、コマンドレットは対話形式でプロンプトを表示し、現在のユーザーを既定値として提案します。 エージェント ID が作成される前に、すべてのユーザー ID と UPN がテナントに対して検証されます。 重複するエントリは自動的に削除されます。

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', '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") -OwnerUserIds @("owner1@contoso.com")

この例では、現在のセッションで作成されたエージェント ID ブループリントを使用して、指定された表示名、スポンサー、所有者を持つエージェント ID を作成します。

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "HR Agent" -SponsorUserIds @("hr-admin@contoso.com") -SponsorGroupIds @("aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb")

この例では、ユーザースポンサーとグループスポンサーの両方でエージェント ID を作成します。

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "Finance Blueprint" -SponsorUserIds @("finance-admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "Finance Agent"

この例では、エージェント ID を作成します。 指定されていない場合、コマンドレットはスポンサーと所有者を求めます。

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

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

• id — 作成されたエージェント ID (サービス プリンシパル) の一意の識別子。
• appId — エージェント ID に関連付けられているアプリケーション ID。
• displayName — エージェント ID の表示名。
• createdDateTime — エージェント ID が作成された日時。
• AgentIdentityBlueprintId — 親エージェント ID ブループリントの ID。

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

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

• AgentIdentity.Create.All

コマンドレットは、New-EntraAgentIdentityBlueprintによって設定された格納されたエージェント ID ブループリント ID ($script:CurrentAgentBlueprintId) に依存します。 ブループリント ID が格納されていない場合、コマンドレットはエラーで失敗します。

エージェント ID を作成した後、コマンドレットは、ID と AppId をモジュール レベルの変数 ($script:CurrentAgentIdentityId、 $script:CurrentAgentIdentityAppId) と、他のコマンドレットで使用するグローバル変数 ($global:EntraCurrentAgentIdentityId) に格納します。

このコマンドレットは、v1.0 Microsoft Graph エンドポイント (/v1.0/servicePrincipals/Microsoft.Graph.AgentIdentity) を使用し、伝達遅延を処理するための再試行ロジック (最大 10 回の試行と 10 秒の待機) が含まれています。

スポンサーまたは所有者のパラメーターが指定されていない場合、コマンドレットは次の対話型モードに入ります。

• 現在サインインしているユーザーを検索し、既定のスポンサー/所有者として提供します
• テナントに対するすべてのユーザー ID と UPN を検証し、ユーザーが見つからない場合は修正を求めます
• テナントに対してグループ ID を検証し、見つからないものはすべてスキップします
• 反復プロンプトで追加のスポンサー/所有者を追加できるようにします