unifiedRoleDefinition: assignedPrincipals

  • [アーティクル]

名前空間: microsoft.graph

重要

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

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

特定のプリンシパルの直接および推移的なロールの割り当てを一覧表示するには、 推移的RoleAssignments 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

呼び出し元に、結果セットに含まれる一部のオブジェクトのプロパティを読み取るアクセス許可がない場合、応答は アクセスできないメンバー オブジェクト パターンに対して返される限られた情報に 従います。

オブジェクトのアクセス許可を必要とする可能性があるプロパティを読み取るために、オブジェクトに関する情報を取得するアクセス許可を付与します。 詳細については、「 ユーザー、 グループ、 およびサービス プリンシパルのアクセス許可」を参照してください。

HTTP 要求

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

関数パラメーター

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

パラメーター 型 説明
推移 ブール型 グループ メンバーシップを通じて割り当てられたプリンシパルを含める (直接または推移的) かどうかを示します。 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 つの直接ロールの割り当て
  • User1 から Group1 と Group2 への 2 つの推移的なロールの割り当て
  • ユーザー 2 と User3 から Group3 への 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"
    }
  ]
}