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": []
}