Adicionar um membro

Namespace: microsoft.graph

Use essa API para adicionar um membro (usuário, grupo ou dispositivo) a uma unidade administrativa. Atualmente, só é possível adicionar um membro por vez a uma unidade administrativa.

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

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Permissões para adicionar um usuário, grupo ou dispositivo existente

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) AdministrativeUnit.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte.
Application AdministrativeUnit.ReadWrite.All

Importante

Para acesso delegado usando contas corporativas ou de estudante, o usuário conectado deve ser um usuário membro ou 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. O Administrador de Função Privilegiada é a função com menos privilégios com suporte para esta operação.

Permissões para criar um novo grupo

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte.
Application Group.Create and AdministrativeUnit.Read.All, Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All

Importante

Para criar um novo grupo em uma unidade administrativa, a entidade principal de chamada deve receber pelo menos uma das seguintes funções do Microsoft Entra no escopo da unidade administrativa:

  • Administrador de grupos
  • Administrador do usuário

Para cenários somente de aplicativo: além dessas funções, a entidade de serviço requer permissões adicionais para ler o diretório. Essas permissões podem ser concedidas por meio da atribuição de funções do Microsoft Entra com suporte, como a função de Leitores de Diretório; ou podem ser concedidas por meio de permissões do aplicativo Microsoft Graph que permitem a leitura do diretório, como Directory.Read.All.

Solicitação HTTP

A solicitação a seguir adiciona um usuário, grupo ou dispositivo existente à unidade administrativa.

POST /directory/administrativeUnits/{id}/members/$ref

A solicitação a seguir cria um novo grupo na unidade administrativa.

POST /directory/administrativeUnits/{id}/members

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

Adicionando um usuário, grupo ou dispositivo existente

No corpo da solicitação, forneça a ID de um usuário, grupo, dispositivo ou directoryObject a ser adicionado. Se a unidade administrativa for uma unidade administrativa de gerenciamento restrito ("isMemberManagementRestricted": true), o tipo de grupo deverá ser um grupo de segurança do Microsoft Entra. Há suporte apenas para grupos não unificados que são habilitados para segurança, não para email e não para sincronização local.

Criar um novo grupo

A tabela a seguir mostra as propriedades do recurso de grupo a serem especificadas quando você cria um grupo na unidade administrativa.

Propriedade Tipo Descrição
displayName string O nome para exibição no catálogo de endereços do grupo. Obrigatório.
description string Uma descrição para o grupo. Opcional.
isAssignableToRole Booliano Defina como true para permitir que o grupo seja atribuído a uma função do Microsoft Entra. Administrador de função privilegiada é a função menos privilegiada para definir o valor dessa propriedade. Opcional.
mailEnabled Boolean Defina como true para grupos habilitados para email. Obrigatório.
mailNickname string O alias de email do grupo. Esses caracteres não podem ser usados no mailNickName: @()\[]";:.<>,SPACE. Obrigatório.
securityEnabled Boolean Defina como true para grupos habilitados para segurança, incluindo grupos do Microsoft 365. Obrigatório.
owners Coleção directoryObject Esta propriedade representa os proprietários do grupo na hora de criação. Opcional.
membros Coleção directoryObject Esta propriedade representa os membros do grupo na hora de criação. Opcional.
visibility Cadeia de caracteres Especifica a visibilidade de um grupo do Microsoft 365. Os valores possíveis são: Private, Public, HiddenMembershipou vazio (que é interpretado como Public).

Resposta

Se for bem-sucedido, adicionar um objeto existente (usando $ref) retornará 204 No Content o código de resposta. Ele não retorna nada no corpo da resposta.

Ao criar um novo grupo (sem $ref), esse método retorna um código de 201 Created resposta e um objeto de grupo no corpo da resposta. A resposta inclui somente as propriedades padrão do grupo. Você deve fornecer a "@odata.type" : "#microsoft.graph.group" linha no corpo da solicitação para identificar explicitamente o novo membro como um grupo. Um corpo da solicitação sem o correto @odata.type retorna uma mensagem de 400 Bad Request erro.

Exemplos

Exemplo 1: adicionar um usuário ou grupo existente

A solicitação a seguir adiciona um usuário ou grupo existente a uma unidade administrativa.

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/v1.0/directory/administrativeUnits/{id}/members/$ref
Content-type: application/json

{
  "@odata.id":"https://graph.microsoft.com/v1.0/groups/{id}"
}

No corpo da solicitação, forneça o id objeto de usuário ou grupo que você deseja adicionar.

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Exemplo 2: Criar um novo grupo

O exemplo a seguir cria um novo grupo na unidade administrativa. Você deve fornecer a "@odata.type" : "#microsoft.graph.group" linha no corpo da solicitação para identificar explicitamente o novo membro como um grupo. Um corpo da solicitação sem o correto @odata.type retorna uma mensagem de 400 Bad Request erro.

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/v1.0/directory/administrativeUnits/{id}/members
Content-type: application/json

{
  "@odata.type": "#microsoft.graph.group",
  "description": "Self help community for golf",
  "displayName": "Golf Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "golfassist",
  "securityEnabled": false
}

No corpo da solicitação, forneça as propriedades do objeto de grupo que você deseja adicionar.

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#groups/$entity",
     "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
     "deletedDateTime": null,
     "classification": null,
     "createdDateTime": "2018-12-22T02:21:05Z",
     "description": "Self help community for golf",
     "displayName": "Golf Assist",
     "expirationDateTime": null,
     "groupTypes": [
         "Unified"
     ],
   "isAssignableToRole": null,
     "mail": "golfassist@contoso.com",
     "mailEnabled": true,
     "mailNickname": "golfassist",
     "membershipRule": null,
     "membershipRuleProcessingState": null,
     "onPremisesLastSyncDateTime": null,
     "onPremisesSecurityIdentifier": null,
     "onPremisesSyncEnabled": null,
     "preferredDataLocation": "CAN",
     "preferredLanguage": null,
     "proxyAddresses": [
         "SMTP:golfassist@contoso.com"
     ],
     "renewedDateTime": "2018-12-22T02:21:05Z",
     "resourceBehaviorOptions": [],
     "resourceProvisioningOptions": [],
     "securityEnabled": false,
     "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
     "theme": null,
     "visibility": "Public",
     "onPremisesProvisioningErrors": []
}