Criar roleAssignmentScheduleRequests

Namespace: microsoft.graph

No PIM, execute as seguintes operações por meio do objeto unifiedRoleAssignmentScheduleRequest :

  • Solicite atribuições de função ativas e persistentes para uma entidade de segurança, com ou sem datas de expiração.
  • Ativar, desativar, estender ou renovar uma atribuição de função qualificada para uma entidade de segurança.

Para chamar essa API para atualizar, renovar e estender atribuições para si mesmo, você deve ter a autenticação multifator (MFA) imposta e executar a consulta em uma sessão na qual eles foram desafiados para MFA. Consulte Habilitar a autenticação multifator do Microsoft Entra por usuário para proteger eventos de entrada.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global Governo dos EUA L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante) RoleAssignmentSchedule.ReadWrite.Directory RoleAssignmentSchedule.Remove.Directory, RoleEligibilitySchedule.Remove.Directory, RoleManagement.ReadWrite.Directory
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application RoleAssignmentSchedule.ReadWrite.Directory RoleManagement.ReadWrite.Directory, RoleAssignmentSchedule.Remove.Directory, RoleEligibilitySchedule.Remove.Directory

Importante

Para acesso delegado usando contas corporativas ou de estudante, o usuário conectado deve receber uma função do Microsoft Entra com suporte ou uma função personalizada que conceda as permissões necessárias para esta operação. Esta operação dá suporte às seguintes funções internas, que fornecem apenas o menor privilégio necessário:

  • Para operações de leitura: Leitor Global, Operador de Segurança, Leitor de Segurança, Administrador de Segurança ou Administrador de Função Privilegiada
  • Para operações de gravação: Administrador de Função Privilegiada

Solicitação HTTP

POST /roleManagement/directory/roleAssignmentScheduleRequests

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON do objeto unifiedRoleAssignmentScheduleRequest .

Você pode especificar as propriedades a seguir ao criar um unifiedRoleAssignmentScheduleRequest.

Propriedade Tipo Descrição
ação unifiedRoleScheduleRequestActions Representa o tipo da operação na solicitação de atribuição de função. Os valores possíveis são adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew, unknownFutureValue.
  • adminAssign: para que os administradores atribuam funções a usuários ou grupos.
  • adminRemove: para que os administradores removam usuários ou grupos de funções.
  • adminUpdate: para que os administradores alterem as atribuições de função existentes.
  • adminExtend: para que os administradores estendam atribuições que estão expirando.
  • adminRenew: para que os administradores renovem atribuições expiradas.
  • selfActivate: para que os usuários ativem suas atribuições.
  • selfDeactivate: Para que os usuários desativem suas atribuições ativas.
  • selfExtend: para que os usuários solicitem a extensão de suas atribuições que estão expirando.
  • selfRenew: para que os usuários solicitem a renovação de suas atribuições expiradas.
customData Cadeia de caracteres Campo de texto livre para definir dados personalizados para a solicitação. Opcional.
principalId Cadeia de caracteres Identificador da entidade de segurança que recebeu a atribuição. Obrigatório.
roleDefinitionId Cadeia de caracteres Identificador do objeto unifiedRoleDefinition que está sendo atribuído. Obrigatório.
directoryScopeId Cadeia de caracteres Identificador do objeto de diretório que representa o escopo da atribuição. O escopo de uma atribuição determina o conjunto de recursos para os quais a entidade de segurança recebeu acesso. Escopos de diretório são escopos compartilhados armazenados no diretório que são compreendidos por vários aplicativos. Use / para escopo de todo o locatário. Use appScopeId para limitar o escopo a apenas um aplicativo. É necessário directoryScopeId ou appScopeId .
appScopeId Cadeia de caracteres Identificador do escopo específico do aplicativo quando a atribuição tem como escopo um aplicativo. O escopo de uma atribuição determina o conjunto de recursos para os quais a entidade de segurança recebeu acesso. Escopos de aplicativo são escopos definidos e compreendidos somente por este aplicativo. Use / para escopos de aplicativo em todo o locatário. Use directoryScopeId para limitar o escopo a objetos de diretório específicos, por exemplo, unidades administrativas. É necessário directoryScopeId ou appScopeId .
Justificação Cadeia de caracteres Uma mensagem fornecida por usuários e administradores ao criarem o objeto unifiedRoleAssignmentScheduleRequest .

Ações opcionais para selfDeactivate eadminRemove; podem ser opcionais ou necessárias para outros tipos de ação, dependendo das regras na política vinculada à função do Microsoft Entra. Para obter mais informações, consulte Regras no PIM.
Informações de agendamento requestSchedule O período da solicitação de atribuição de função. No momento, não há suporte para agendamentos recorrentes. Obrigatório.
ticketInfo ticketInfo Detalhes do tíquete vinculados à solicitação de atribuição de função, incluindo detalhes do número do tíquete e do sistema de tíquetes.

Ações opcionais para selfDeactivate eadminRemove; podem ser opcionais ou necessárias para outros tipos de ação, dependendo das regras na política vinculada à função do Microsoft Entra. Para obter mais informações, consulte Regras no PIM.

Resposta

Se for bem-sucedido, esse método retornará um código de 201 Created resposta e um objeto unifiedRoleAssignmentScheduleRequest no corpo da resposta.

Exemplos

Exemplo 1: Administração atribuindo uma função de diretório a uma entidade de segurança

Na solicitação a seguir, o administrador cria uma solicitação para atribuir uma função identificada por fdd7a751-b60b-444a-984c-02652fe8fa1c a uma entidade de segurança identificada pela ID 071cc716-8147-4397-a5ba-b2105951cc0b. O escopo de sua função são todos os objetos de diretório no locatário e a atribuição é permanente.

Solicitação

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"
        }
    }
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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
    }
}

Exemplo 2: usuário ativando sua função qualificada

Solicitação

Na solicitação a seguir, um usuário identificado por principalId071cc716-8147-4397-a5ba-b2105951cc0b ativa sua própria função qualificada para uma função do Microsoft Entra identificada por ID8424c6f0-a189-499e-bbd0-26c1753c96d4. O escopo de sua função são todos os objetos de diretório no locatário e a atribuição é de cinco horas. Para executar essa solicitação, o usuário chamador deve ter a MFA (autenticação multifator) imposta e executar a consulta em uma sessão na qual foi desafiado para MFA.

Para recuperar os detalhes das solicitações de qualificação e identificar a qualificação para ativar, o usuário chamará a API unifiedRoleEligibilitySchedule: filterByCurrentUser .

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"
    }
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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"
    }
}