Compartilhar via


Adicionar um membro

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.

Utilize esta API para adicionar um membro (utilizador, grupo ou dispositivo) a uma unidade administrativa ou para criar um novo grupo numa unidade administrativa. Todos os tipos de grupo podem ser criados numa unidade administrativa.

Nota: Atualmente, só é possível adicionar um membro de cada vez a uma unidade administrativa."

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

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 utilizador, 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

Em cenários delegados com contas escolares ou profissionais, o utilizador com sessão iniciada tem de ser um utilizador membro ou ser-lhe atribuída uma função de Microsoft Entra suportada ou uma função personalizada com uma permissão de função suportada. O Administrador de Funções Com Privilégios é a função com menos privilégios suportada 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 e AdministrativeUnit.Read.All, Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte.
Application Group.Create e AdministrativeUnit.Read.All, Group.ReadWrite.All e AdministrativeUnit.Read.All, Directory.ReadWrite.All

Importante

Para criar um novo grupo numa unidade administrativa, o principal de chamada tem de ter, pelo menos, uma das seguintes funções Microsoft Entra no âmbito da unidade administrativa:

  • Administrador do Grupos
  • Administrador do usuário

Para cenários apenas de aplicação – para além destas funções, o principal de serviço requer permissões adicionais para ler o diretório. Estas permissões podem ser concedidas através da atribuição de funções de Microsoft Entra suportadas, como a função Leitores de Diretórios; ou podem ser concedidas através de permissões de aplicação do Microsoft Graph que permitem ler o diretório, como Directory.Read.All.

Solicitação HTTP

O pedido seguinte adiciona um utilizador, grupo ou dispositivo existente à unidade administrativa.

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

O pedido seguinte cria um novo grupo na unidade administrativa.

POST /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.

Adicionar um utilizador ou grupo existente

No corpo do pedido, forneça o id de um utilizador, grupo, dispositivo ou diretórioObjeto a adicionar. Se a unidade administrativa for uma unidade administrativa de gestão restrita (isMemberManagementRestricted=true), o tipo de grupo tem de ser um grupo de segurança Microsoft Entra. Apenas são suportados os grupos não unificados com segurança ativada, não com o e-mail ativado e não a sincronização no local ativada.

Criar um novo grupo

A tabela seguinte mostra as propriedades do recurso de grupo a especificar quando 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 verdadeiro para permitir que o grupo seja atribuído a uma função de Microsoft Entra. O Administrador de Função Privilegiada é a função com menos privilégios para definir o valor desta 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, HiddenMembership ou vazio (que é interpretado como Public).

Resposta

Se for bem-sucedido, adicionar um objeto existente (com $ref) devolve 204 No Content o código de resposta. Não devolve nada no corpo da resposta.

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

Exemplos

Exemplo 1: Adicionar um utilizador ou grupo existente

O seguinte irá adicionar um utilizador ou grupo existente à unidade administrativa.

Solicitação

O exemplo a seguir mostra uma solicitação.

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

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

No corpo do pedido, forneça o id objeto de utilizador, grupo ou dispositivo que pretende adicionar.

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Exemplo 2: Criar um novo grupo

O exemplo seguinte cria um novo grupo na unidade administrativa. Tem de fornecer a "@odata.type" : "#microsoft.graph.group" linha no corpo do pedido para identificar explicitamente o novo membro como um grupo. Um corpo do pedido sem o correto @odata.type devolve uma mensagem de 400 Bad Request erro.

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/beta/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 do pedido, forneça as propriedades do objeto de grupo que pretende 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/beta/$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": []
}