次の方法で共有

unifiedRoleDefinition: assignedPrincipals

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

異なる範囲の特定の役割に割り当てられたセキュリティ プリンシパル (ユーザー、グループ、サービス プリンシパル) のリストを直接または推移的に取得します。 クエリ パラメーター $count を使用して数値を取得することもできます。

この API は、ディレクトリ (Microsoft Entra ID) プロバイダーでのみサポートされています。

特定のプリンシパルの直接および推移的な役割の割り当てを一覧表示するには、List transitiveRoleAssignments API を使用します。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類 最小特権アクセス許可 より高い特権のアクセス許可
委任 (職場または学校のアカウント) RoleManagement.Read.Directory Directory.Read.All、RoleManagement.ReadWrite.Directory
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション RoleManagement.Read.Directory Directory.Read.All、RoleManagement.ReadWrite.Directory

職場または学校アカウントを使用した委任されたシナリオでは、サインインしているユーザーに、サポートされている Microsoft Entra ロール または次のいずれかのロールのアクセス許可を持つカスタム ロールを割り当てる必要があります。

  • microsoft.directory/roleDefinitions/standard/read (最小特権)
  • microsoft.directory/roleDefinitions/allProperties/read
  • microsoft.directory/roleDefinitions/allProperties/allTasks

この操作でサポートされる最小特権ロールは、最小から最も特権の順に次のとおりです。

  • ディレクトリ リーダー
  • グローバル閲覧者
  • 特権ロール管理者

重要

アプリケーションが directoryObject 型のコレクションを返すリレーションシップをクエリするときに、特定のリソース型を読み取るアクセス許可がない場合、その型のメンバーが返されますが、情報は限られます。 たとえば、@odata.type プロパティでは、オブジェクト型と ID だけが返され、その他のプロパティは null と表示されます。 この動作により、アプリケーションは、Directory.* 権限が付与されたアクセス許可のセットに依存するのではなく、必要な最小限のアクセス許可を要求できます。 詳細については、「アクセスできないメンバー オブジェクトについて、限定された情報が返される」を参照してください。

HTTP 要求

GET /roleManagement/directory/roleDefinitions/{unifiedRoleDefinitionId}/assignedPrincipals(transitive=@transitive,directoryScopeType='@directoryScopeType',directoryScopeId='@directoryScopeId')

関数パラメーター

要求 URL で、次のクエリ パラメーターに値を指定します。 次の表に、この関数で使用できるパラメーターを示します。

パラメーター 型 説明
transitive ブール型 グループ メンバーシップ (直接または推移的) を通じて割り当てられたプリンシパルを含めるかどうかを示します。 既定では false です。
directoryScopeType String 割り当てられたプリンシパルを取得するディレクトリ スコープ。 サポートされている値は tenant、administrativeUnit、resource です。
directoryScopeId String 割り当てられたプリンシパルを取得するディレクトリ スコープの ID。 既定では、すべてのスコープが考慮されます。

また、サポートされているすべての関数パラメーターを 1 つの要求に組み合わせて、詳細な結果を得ることもできます。

directoryScopeType のクエリ パターンの例

範囲 クエリ サポート対象
すべてのスコープ /assignedPrincipals(transitive={true | false}) すべての役割
テナント スコープ /assignedPrincipals(directoryScopeType='tenant', transitive={true | false}) すべての役割
すべての管理単位スコープ /assignedPrincipals(directoryScopeType='administrativeUnit', transitive={true | false}) ディレクトリ ロール
特定の管理単位スコープ /assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) ディレクトリ ロール
すべてのリソース スコープ /assignedPrincipals(directoryScopeType='resource', transitive={true | false}) ディレクトリ ロール
特定のリソース スコープ /assignedPrincipals(directoryScopeType='resource', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) ディレクトリ ロール

オプションのクエリ パラメーター

このメソッドは、応答をカスタマイズするための $count、$select、$filter、$orderby OData クエリ パラメーターをサポートします。 OData キャストを使用して、オブジェクトの種類でフィルター処理することもできます。 たとえば、/assignedPrincipals(transitive=false)/microsoft.graph.user および /assignedPrincipals(transitive=true)/microsoft.graph.servicePrincipal/$count などです。 一般的な情報については、「OData クエリ パラメーター」を参照してください。

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。
ConsistencyLevel 最終的。 必須。 ConsistencyLevel の使用方法の詳細については、「ディレクトリ オブジェクトの詳細クエリ機能」を参照してください。

要求本文

このメソッドには、要求本文を指定しません。

応答

成功した場合、この関数は 200 OK 応答コードと、応答本文で directoryObject コレクションを返します。

例

このセクションの例では、次のロールの割り当てシナリオを検討してください。 User1 という名前のユーザーには、次のような直接的および推移的な役割の両方が割り当てられています。

User グループ 役割 範囲
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Role1 Scope1
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Role1 Scope2
Group1
86b38db7-6e8b-4ad2-b2aa-ced7f09486c1
(User1 はメンバーです)		 Role1 Scope1
Group2
182351a6-d974-4d18-88ae-8a148da44cd2
(User1 はメンバーです)		 Role1 Scope1
Group3
b93d5379-a464-4db5-b8e1-694910f1e11e
(User2 はメンバーです)
(User3 はメンバーです)		 Role1 Scope3
  • User1 には、Scope1 スコープで Role1 ロールが直接割り当てられます。
  • User1 には、Scope2 スコープで Role1 ロールが直接割り当てられます。
  • User1 は Group1 グループのメンバーであり、Group1 には Scope1 スコープで Role1 ロールが割り当てられます。
  • User1 は Group2 グループのメンバーであり、Group2 は Scope1 スコープで Role1 ロールが割り当てられます。
  • User2 は Group3 グループのメンバーであり、Group3 は Scope3 スコープで Role1 ロールが割り当てられます。
  • User3 は Group3 グループのメンバーであり、Group3 は Scope3 スコープで Role1 ロールが割り当てられます。

例 1: すべてのスコープに対して直接および推移的に割り当てられたプリンシパルの数を取得する

要求

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(transitive=true)/$count

応答

上記の要求は、次のロールの割り当てを表す 6 のカウントを返します。

  • Scope1 と Scope2 での User1 への 2 つの直接ロールの割り当て
  • Group1 と Group2 を通じた User1 への 2 つの推移的なロールの割り当て
  • Group3 を通じた User2 と User3 への 2 つの推移的なロールの割り当て。
HTTP/1.1 200 OK
Content-type: text/plain

6

同じシナリオに基づいて、次の例は各クエリ パターンに対して返される数を示しています。

例 カウント
/assignedPrincipals(transitive=false)/$count 4
(User1、Group1、Group2、Group3)
/assignedPrincipals(transitive=false)/microsoft.graph.user/$count 1
(User1)
/assignedPrincipals(transitive=true)/microsoft.graph.user/$count 3
(User1、User2、User3)
/assignedPrincipals(transitive=false)/microsoft.graph.group/$count 3
(Group1、Group2、Group3)
/assignedPrincipals(transitive=true)/microsoft.graph.group/$count 3
(Group1、Group2、Group3)

例 2: 特定の管理単位スコープとディレクトリ ロールに直接割り当てられたプリンシパルを取得する

要求

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='d0c2e067-9ae9-4dbf-a280-51a51c46f432')

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f"
    }
  ]
}

例 3: すべてのスコープに対して直接割り当てられたプリンシパルを取得する

要求

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}

例 4: テナント全体のスコープに対してのみ直接割り当てられたユーザーを取得する

要求

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='tenant')/microsoft.graph.user

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users",
  "value": [
    {
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    }
  ]
}

例 5: 直接割り当てられたプリンシパルとインライン カウントを取得する

次の例では、直接割り当てられたプリンシパルを取得し、インライン カウントを表示します。

要求

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals?$count=true

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.count": 4,
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}