Criar roleAssignmentScheduleRequests

Namespace: microsoft.graph

No PIM, execute as seguintes operações através do objeto unifiedRoleAssignmentScheduleRequest :

  • Peça atribuições de funções ativas e persistentes para um principal, com ou sem datas de expiração.
  • Ativar, desativar, expandir ou renovar uma atribuição de função elegível para um principal.

Para chamar esta API para atualizar, renovar e expandir atribuições para si próprio, tem de ter a autenticação multifator (MFA) imposta e executar a consulta numa sessão em que foram desafiadas para a MFA. Veja Ativar a autenticação multifator do Microsoft Entra por utilizador para proteger eventos de início de sessão.

Esta API está disponível nas seguintes implementações de cloud nacionais.

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

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
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

Em cenários delegados com contas escolares ou profissionais, o utilizador com sessão iniciada tem de ter uma função suportada do Microsoft Entra ou uma função personalizada com uma permissão de função suportada. As seguintes funções com menos privilégios são suportadas para esta operação.

  • 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 escrita: Administrador de Funções Com Privilégios

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 do pedido, forneça uma representação JSON do objeto unifiedRoleAssignmentScheduleRequest .

Pode especificar as seguintes propriedades ao criar um unifiedRoleAssignmentScheduleRequest.

Propriedade Tipo Descrição
ação unifiedRoleScheduleRequestActions Representa o tipo da operação no pedido de atribuição de função. Os valores possíveis são adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew, unknownFutureValue.
  • adminAssign: para os administradores atribuirem funções a utilizadores ou grupos.
  • adminRemove: para os administradores removerem utilizadores ou grupos de funções.
  • adminUpdate: para os administradores alterarem as atribuições de funções existentes.
  • adminExtend: para os administradores prolongarem as atribuições prestes a expirar.
  • adminRenew: para os administradores renovarem as atribuições expiradas.
  • selfActivate: para que os utilizadores ativem as respetivas atribuições.
  • selfDeactivate: para os utilizadores desativarem as respetivas atribuições ativas.
  • selfExtend: para que os utilizadores peçam para prolongar as atribuições prestes a expirar.
  • selfRenew: para os utilizadores pedirem a renovação das respetivas atribuições expiradas.
customData Cadeia de caracteres Campo de texto livre para definir quaisquer dados personalizados para o pedido. Opcional.
principalId Cadeia de caracteres Identificador do principal ao qual foi concedida a atribuição. Obrigatório.
roleDefinitionId Cadeia de caracteres Identificador do objeto unifiedRoleDefinition que está a ser atribuído. Obrigatório.
directoryScopeId Cadeia de caracteres Identificador do objeto de diretório que representa o âmbito da atribuição. O âmbito de uma atribuição determina o conjunto de recursos ao qual foi concedido acesso ao principal. Os âmbitos de diretório são âmbitos partilhados armazenados no diretório que são compreendidos por várias aplicações. Utilize / para o âmbito ao nível do inquilino. Utilize appScopeId para limitar o âmbito apenas a uma aplicação. O directoryScopeId ou o appScopeId são necessários.
appScopeId Cadeia de caracteres Identificador do âmbito específico da aplicação quando a atribuição está confinada a uma aplicação. O âmbito de uma atribuição determina o conjunto de recursos ao qual foi concedido acesso ao principal. Os âmbitos da aplicação são âmbitos definidos e compreendidos apenas por esta aplicação. Utilize / para âmbitos de aplicações ao nível do inquilino. Utilize directoryScopeId para limitar o âmbito a determinados objetos de diretório, por exemplo, unidades administrativas. O directoryScopeId ou o appScopeId são necessários.
justificação Cadeia de caracteres Uma mensagem fornecida por utilizadores e administradores ao criar criam o objeto unifiedRoleAssignmentScheduleRequest .

Opcional para selfDeactivate e adminRemove ações; pode ser opcional ou necessário para outros tipos de ação consoante as regras na política que está ligada à função Microsoft Entra. Para obter mais informações, veja Regras no PIM.
scheduleInfo requestSchedule O período do pedido de atribuição de função. Atualmente, as agendas periódicas não são suportadas. Obrigatório.
ticketInfo ticketInfo Detalhes do pedido de permissão associados ao pedido de atribuição de função, incluindo detalhes do número da permissão e do sistema de pedidos.

Opcional para selfDeactivate e adminRemove ações; pode ser opcional ou necessário para outros tipos de ação consoante as regras na política que está ligada à função Microsoft Entra. Para obter mais informações, veja Regras no PIM.

Resposta

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

Exemplos

Exemplo 1: o administrador que atribui uma função de diretório a um principal

No pedido seguinte, o administrador cria um pedido para atribuir uma função identificada por fdd7a751-b60b-444a-984c-02652fe8fa1c a um principal identificado pelo ID 071cc716-8147-4397-a5ba-b2105951cc0b. O âmbito da respetiva função é todos os objetos de diretório no inquilino 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: Utilizador a ativar a função elegível

Solicitação

No pedido seguinte, um utilizador identificado pelo principalId071cc716-8147-4397-a5ba-b2105951cc0b ativa a sua própria função elegível para uma função do Microsoft Entra identificada pelo ID 8424c6f0-a189-499e-bbd0-26c1753c96d4. O âmbito da respetiva função é todos os objetos de diretório no inquilino e a atribuição é de cinco horas. Para executar este pedido, o utilizador que está a chamar tem de ter a autenticação multifator (MFA) imposta e executar a consulta numa sessão na qual foi desafiada para a MFA.

Para obter os detalhes dos respetivos pedidos de elegibilidade e identificar a elegibilidade para ativação, o utilizador irá 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"
    }
}