roleAssignmentScheduleRequests を作成する

名前空間: microsoft.graph

PIM で、 unifiedRoleAssignmentScheduleRequest オブジェクトを介して次の操作を実行します。

  • 有効期限の有無にかかわらず、プリンシパルのアクティブロールと永続的なロールの割り当てを要求します。
  • プリンシパルの対象となるロールの割り当てをアクティブ化、非アクティブ化、拡張、または更新します。

この API を呼び出して割り当てを更新、更新、および拡張するには、多要素認証 (MFA) を適用し、MFA に対してチャレンジされたセッションでクエリを実行する必要があります。 「ユーザーごとの Microsoft Entra 多要素認証を有効にしてサインイン イベントをセキュリティで保護する」を参照してください。

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

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

アクセス許可

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

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

委任されたシナリオの場合、サインインしているユーザーには、次の Microsoft Entra ロールの少なくとも 1 つを割り当てる必要があります。

  • 読み取り操作の場合: グローバル 閲覧者、セキュリティ オペレーター、セキュリティ閲覧者、セキュリティ管理者、または特権ロール管理者
  • 書き込み操作の場合: 特権ロール管理者

HTTP 要求

POST /roleManagement/directory/roleAssignmentScheduleRequests

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。
Content-Type application/json. 必須です。

要求本文

要求本文で、 unifiedRoleAssignmentScheduleRequest オブジェクトの JSON 表現を指定します。

unifiedRoleAssignmentScheduleRequest を作成するときに、次のプロパティを指定できます。

プロパティ 種類 説明
action unifiedRoleScheduleRequestActions ロールの割り当て要求に対する操作の種類を表します。 使用可能な値: adminAssignadminUpdateadminRemoveselfActivateselfDeactivateadminExtendadminRenewselfExtendselfRenewunknownFutureValue
  • adminAssign: 管理者がユーザーまたはグループにロールを割り当てる場合。
  • adminRemove: 管理者がロールからユーザーまたはグループを削除する場合。
  • adminUpdate: 管理者が既存のロールの割り当てを変更する場合。
  • adminExtend: 管理者が期限切れの割り当てを延長する場合。
  • adminRenew: 管理者が期限切れの割り当てを更新する場合。
  • selfActivate: ユーザーが自分の割り当てをアクティブ化します。
  • selfDeactivate: ユーザーがアクティブな割り当てを非アクティブ化する。
  • selfExtend: ユーザーが期限切れの割り当ての延長を要求する。
  • selfRenew: ユーザーが期限切れの割り当ての更新を要求する。
customData String 要求のカスタム データを定義するフリー テキスト フィールド。 省略可能。
principalId String 割り当てが付与されているプリンシパルの識別子。 必須です。
roleDefinitionId String 割り当てられている unifiedRoleDefinition オブジェクトの識別子。 必須です。
directoryScopeId String 割り当てのスコープを表すディレクトリ オブジェクトの識別子。 割り当てのスコープによって、プリンシパルにアクセス権が付与されているリソースのセットが決まります。 ディレクトリ スコープは、複数のアプリケーションによって認識されるディレクトリに格納されている共有スコープです。 テナント全体のスコープには / を使用します。 appScopeId を使用して、スコープをアプリケーションのみに制限します。 directoryScopeId または appScopeId が必要です。
appScopeId String 割り当てがアプリにスコープ設定されている場合のアプリ固有のスコープの識別子。 割り当てのスコープによって、プリンシパルにアクセス権が付与されているリソースのセットが決まります。 アプリ スコープは、このアプリケーションによってのみ定義および理解されるスコープです。 テナント全体のアプリ スコープに / を使用します。 directoryScopeId を使用して、スコープを特定のディレクトリ オブジェクト (管理単位など) に制限します。 directoryScopeId または appScopeId が必要です。
ジャスティフィケーション String unifiedRoleAssignmentScheduleRequest オブジェクトを作成するときに、ユーザーと管理者によって提供されるメッセージ。

selfDeactivateアクションとadminRemoveアクションの場合は省略可能です。Microsoft Entra ロールにリンクされているポリシーのルールによっては、その他のアクションの種類に対して省略可能または必須になる場合があります。 詳細については、「 PIM のルール」を参照してください。
scheduleInfo requestSchedule ロールの割り当て要求の期間。 定期的なスケジュールは現在サポートされていません。 必須です。
ticketInfo ticketInfo チケット番号とチケット システムの詳細を含む、ロール割り当て要求にリンクされたチケットの詳細。

selfDeactivateアクションとadminRemoveアクションの場合は省略可能です。Microsoft Entra ロールにリンクされているポリシーのルールによっては、その他のアクションの種類に対して省略可能または必須になる場合があります。 詳細については、「 PIM のルール」を参照してください。

応答

成功した場合、このメソッドは 201 Created 応答コードと、応答本文の unifiedRoleAssignmentScheduleRequest オブジェクトを返します。

例 1: 管理者がディレクトリ ロールをプリンシパルに割り当てる

次の要求では、管理者は ID 071cc716-8147-4397-a5ba-b2105951cc0bで識別されるプリンシパルにfdd7a751-b60b-444a-984c-02652fe8fa1cによって識別されるロールを割り当てる要求を作成します。 ロールのスコープはテナント内のすべてのディレクトリ オブジェクトであり、割り当ては永続的です。

要求

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests
Content-Type: application/json

{
    "action": "adminAssign",
    "justification": "Assign Groups Admin to IT Helpdesk group",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "scheduleInfo": {
        "startDateTime": "2022-04-10T00:00:00Z",
        "expiration": {
            "type": "NoExpiration"
        }
    }
}

応答

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

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
    "status": "Provisioned",
    "createdDateTime": "2022-04-11T11:50:03.9014347Z",
    "completedDateTime": "2022-04-11T11:50:05.9999343Z",
    "approvalId": null,
    "customData": null,
    "action": "adminAssign",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
    "justification": "Assign Groups Admin to IT Helpdesk group",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2022-04-11T11:50:05.9999343Z",
        "recurrence": null,
        "expiration": {
            "type": "noExpiration",
            "endDateTime": null,
            "duration": null
        }
    },
    "ticketInfo": {
        "ticketNumber": null,
        "ticketSystem": null
    }
}

例 2: 資格のあるロールをアクティブ化するユーザー

要求

次の要求では、principalId071cc716-8147-4397-a5ba-b2105951cc0b によって識別されたユーザーが、ID 8424c6f0-a189-499e-bbd0-26c1753c96d4によって識別される Microsoft Entra ロールに対して、自分の適格なロールをアクティブ化します。 ロールのスコープはテナント内のすべてのディレクトリ オブジェクトであり、割り当ては 5 時間です。 この要求を実行するには、呼び出し元のユーザーに多要素認証 (MFA) が適用され、MFA に対してチャレンジされたセッションでクエリを実行する必要があります。

適格性要求の詳細を取得し、アクティブ化する資格を特定するために、ユーザーは unifiedRoleEligibilitySchedule: filterByCurrentUser API を 呼び出します。

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests/
Content-Type: application/json

{
    "action": "selfActivate",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "justification": "I need access to the Attribute Administrator role to manage attributes to be assigned to restricted AUs",
    "scheduleInfo": {
        "startDateTime": "2022-04-14T00:00:00.000Z",
        "expiration": {
            "type": "AfterDuration",
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}

応答

次の例は応答を示しています。

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

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "911bab8a-6912-4de2-9dc0-2648ede7dd6d",
    "status": "Granted",
    "createdDateTime": "2022-04-13T08:52:32.6485851Z",
    "completedDateTime": "2022-04-14T00:00:00Z",
    "approvalId": null,
    "customData": null,
    "action": "selfActivate",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "911bab8a-6912-4de2-9dc0-2648ede7dd6d",
    "justification": "I need access to the Attribute Administrator role to manage attributes to be assigned to restricted AUs",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2022-04-14T00:00:00Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDuration",
            "endDateTime": null,
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}