Partilhar via


Criar roleAssignmentScheduleRequests

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie um novo objeto unifiedRoleAssignmentScheduleRequest . Esta operação permite que os administradores e os utilizadores adicionem, removam, expandam ou renovem atribuições. 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. Veja Ativar a autenticação multifator 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

Importante

Em cenários delegados com contas escolares ou profissionais, o utilizador com sessão iniciada tem de ter uma função de Microsoft Entra suportada 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 .

A tabela seguinte lista as propriedades necessárias quando cria o unifiedRoleAssignmentScheduleRequest.

Propriedade Tipo Descrição
id Cadeia de caracteres O identificador exclusivo para unifiedRoleAssignmentScheduleRequest. Chave, não anulável, Só de leitura.
ação Cadeia de caracteres Representa o tipo da operação na atribuição de função. Os valores possíveis são:
  • 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.
principalId Cadeia de caracteres Identificador do principal ao qual a atribuição está a ser concedida.
roleDefinitionId Cadeia de caracteres Identificador da unifiedRoleDefinition para a qual a atribuição se destina. Somente leitura.
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.
appScopeId Cadeia de caracteres Identificador do âmbito específico da aplicação quando o âmbito de atribuição é específico da 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.
isValidationOnly Booliano Especifica se a chamada é uma validação ou uma chamada real. Defina esta propriedade apenas se quiser marcar se uma ativação está sujeita a regras adicionais, como a MFA, antes de submeter realmente o pedido.
targetScheduleId Cadeia de caracteres ID do objeto de agendamento anexado à atribuição.
justificação Cadeia de caracteres Uma mensagem fornecida por utilizadores e administradores ao criar o pedido sobre o motivo pelo qual é necessário.
scheduleInfo requestSchedule O objeto schedule do pedido de atribuição de função.
ticketInfo ticketInfo O objeto ticketInfo anexado ao pedido de atribuição de função, que inclui detalhes do número da permissão e do sistema de pedidos de suporte.

Resposta

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

Quando o utilizador de chamada não foi desafiado para autenticação multifator durante a sessão de início de sessão, um pedido com a ação SelfActivate falha e devolve um 400 Bad request código de resposta.

Exemplos

Exemplo 1: Administração atribuir uma função de diretório a um principal

Solicitação

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 ID07706ff1-46c7-4847-ae33-3003830675a1. O âmbito da respetiva função é todos os objetos de diretório no inquilino e a atribuição é permanente, ou seja, não expira.

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

{
  "action": "AdminAssign",
  "justification": "Assign User Admin to IT Helpdesk (User) group",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
  "scheduleInfo": {
    "startDateTime": "2021-07-01T00:00:00Z",
    "expiration": {
      "type": "NoExpiration"
    }
  }
}

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/beta/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
  "id": "b5a22921-656a-4429-9c4e-59a5f576614d",
  "status": "Provisioned",
  "createdDateTime": "2021-07-27T09:18:40.2029365Z",
  "completedDateTime": "2021-07-27T09:18:42.7811184Z",
  "approvalId": null,
  "customData": null,
  "action": "AdminAssign",
  "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "appScopeId": null,
  "isValidationOnly": false,
  "targetScheduleId": "b5a22921-656a-4429-9c4e-59a5f576614d",
  "justification": "Assign User Admin to IT Helpdesk (User) group",
  "createdBy": {
    "application": null,
    "device": null,
    "user": {
      "displayName": null,
      "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f"
    }
  },
  "scheduleInfo": {
    "startDateTime": "2021-07-27T09:18:42.7811184Z",
    "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 principalIdc6ad1942-4afa-47f8-8d48-afb5d8d69d2f ativa a sua própria função elegível identificada pelo 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3. 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.

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

{
    "action": "SelfActivate",
    "principalId": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f",
    "roleDefinitionId": "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
    "directoryScopeId": "/",
    "justification": "Need to update app roles for selected apps.",
    "scheduleInfo": {
        "startDateTime": "2021-08-17T17:40: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/beta/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "163daf73-8746-4996-87de-ab71dc624bf9",
    "status": "Granted",
    "createdDateTime": "2021-08-17T17:39:36.7040696Z",
    "completedDateTime": "2021-08-17T17:40:00Z",
    "approvalId": null,
    "customData": null,
    "action": "SelfActivate",
    "principalId": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f",
    "roleDefinitionId": "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "163daf73-8746-4996-87de-ab71dc624bf9",
    "justification": "Need to update app roles for selected apps.",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2021-08-17T17:40:00Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDuration",
            "endDateTime": null,
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}