Gerir grupos no Microsoft Graph

Os grupos no Microsoft Graph são contentores para principais, como utilizadores, dispositivos ou aplicações que partilham acesso a recursos. Facilitam a gestão de acesso ao agrupar principais em vez de geri-los individualmente.

O tipo de recurso de grupo no Microsoft Graph fornece APIs para criar e gerir tipos de grupo suportados e as respetivas funcionalidades.

Observação

• Só pode criar grupos com contas escolares ou profissionais. As contas pessoais da Microsoft não são compatíveis com grupos.
• Todas as operações relacionadas com grupos no Microsoft Graph precisam do consentimento do administrador.

Tipos de grupos suportados no Microsoft Graph

O Microsoft Graph suporta estes tipos de grupos:

• Grupos do Microsoft 365
• Grupos de segurança
• Grupos de segurança habilitados para email
• Grupos de distribuição

Observação

Os grupos de distribuição dinâmicos não são suportados no Microsoft Graph.

A tabela seguinte mostra como identificar tipos de grupos que utilizam as respetivas propriedades e se podem ser geridos através da API de grupos do Microsoft Graph. Os principais diferenciadores são os valores nas propriedades groupTypes, mailEnabled e securityEnabled de um grupo.

Tipo	groupTypes	mailEnabled	securityEnabled	Gerido através do Microsoft Graph
Grupos do Microsoft 365	["Unified"]	true	true ou false	Sim
Grupos de segurança	[]	false	true	Sim
Grupos de segurança habilitados para email	[]	true	true	Não (só de leitura)
Grupos de distribuição	[]	true	false	Não (só de leitura)

Para obter mais informações, veja Comparar grupos no Microsoft Entra ID.

Grupos do Microsoft 365

Grupos do Microsoft 365 foram concebidos para colaboração e fornecem acesso a recursos partilhados, como:

• Conversações e calendário do Outlook.
• Ficheiros do SharePoint e site de equipa.
• Bloco de notas do OneNote.
• Planner planos.
• Intune gestão de dispositivos.

Eis um exemplo de um grupo do Microsoft 365 no formato JSON:

HTTP/1.1 201 Created
Content-type: application/json

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "4c5ee71b-e6a5-4343-9e2c-4244bc7e0938",
    "displayName": "OutlookGroup101",
    "groupTypes": ["Unified"],
    "mailEnabled": true,
    "securityEnabled": false,
    "mail": "outlookgroup101@service.microsoft.com",
    "visibility": "Public"
}

Para saber mais sobre Grupos do Microsoft 365, consulte Descrição geral do Grupos do Microsoft 365 no Microsoft Graph.

Grupos de segurança e grupos de segurança habilitados para email.

Os grupos de segurança controlam o acesso aos recursos. Podem incluir utilizadores, outros grupos, dispositivos e principais de serviço.

Os grupos de segurança com capacidade de correio funcionam como grupos de segurança, mas também permitem a comunicação por e-mail. Estes grupos são só de leitura no Microsoft Graph. Para mais informações, consulte Gerenciar grupos de segurança habilitados para email.

Exemplo de um grupo de segurança no formato JSON:

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mailEnabled": false,
    "securityEnabled": true
}

Associação a um grupo

Os grupos podem ter associações estáticas ou dinâmicas. A associação dinâmica utiliza regras para adicionar ou remover membros automaticamente com base nas respetivas propriedades. Nem todos os tipos de objeto podem ser membros do Microsoft 365 e grupos de segurança.

A tabela a seguir mostra os tipos de membros que podem ser adicionados a grupos de segurança ou grupos do Microsoft 365.

Tipo de objeto	Membro do grupo de segurança	Membro do Microsoft 365 grupo
Usuário
Grupo de segurança
Grupo Microsoft 365
Dispositivo
Entidade de serviço
Contatos organizacionais

Associação dinâmica

A associação dinâmica significa que os principais são adicionados ou removidos do grupo com base nas respetivas propriedades. Por exemplo, um grupo pode ser definido para incluir todos os utilizadores no departamento de "Marketing". Quando um utilizador é adicionado a esse departamento, é adicionado automaticamente ao grupo. Da mesma forma, se um utilizador sair do departamento, será removido do grupo.

Apenas os utilizadores e dispositivos podem ser membros de um grupo dinâmico. A associação dinâmica requer uma licença P1 Microsoft Entra ID para cada utilizador exclusivo num grupo dinâmico.

A regra de associação é definida com a sintaxe da regra de grupo dinâmica Microsoft Entra ID.

Exemplo de uma regra de associação dinâmica:

"membershipRule": "user.department -eq \"Marketing\""

A associação dinâmica requer o "DynamicMembership" valor na propriedade groupTypes . A regra de associação dinâmica pode ser ativada ou desativada através da propriedade membershipRuleProcessingState. Pode atualizar um grupo da associação estática para a associação dinâmica.

Pedido de exemplo para criar um grupo dinâmico do Microsoft 365:

HTTP

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mailEnabled": true,
    "mailNickname": "marketing",
    "securityEnabled": false,
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "on"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	Description = "Marketing department folks",
	DisplayName = "Marketing department",
	GroupTypes = new List<string>
	{
		"Unified",
		"DynamicMembership",
	},
	MailEnabled = true,
	MailNickname = "marketing",
	SecurityEnabled = false,
	MembershipRule = "user.department -eq \"Marketing\"",
	MembershipRuleProcessingState = "on",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

CLI

mgc groups create --body '{\
    "description": "Marketing department folks",\
    "displayName": "Marketing department",\
    "groupTypes": [\
        "Unified",\
        "DynamicMembership"\
    ],\
    "mailEnabled": true,\
    "mailNickname": "marketing",\
    "securityEnabled": false,\
    "membershipRule": "user.department -eq \"Marketing\"",\
    "membershipRuleProcessingState": "on"\
}\
'

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Ir

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewGroup()
description := "Marketing department folks"
requestBody.SetDescription(&description) 
displayName := "Marketing department"
requestBody.SetDisplayName(&displayName) 
groupTypes := []string {
	"Unified",
	"DynamicMembership",
}
requestBody.SetGroupTypes(groupTypes)
mailEnabled := true
requestBody.SetMailEnabled(&mailEnabled) 
mailNickname := "marketing"
requestBody.SetMailNickname(&mailNickname) 
securityEnabled := false
requestBody.SetSecurityEnabled(&securityEnabled) 
membershipRule := "user.department -eq \"Marketing\""
requestBody.SetMembershipRule(&membershipRule) 
membershipRuleProcessingState := "on"
requestBody.SetMembershipRuleProcessingState(&membershipRuleProcessingState) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Post(context.Background(), requestBody, nil)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Group group = new Group();
group.setDescription("Marketing department folks");
group.setDisplayName("Marketing department");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
groupTypes.add("DynamicMembership");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("marketing");
group.setSecurityEnabled(false);
group.setMembershipRule("user.department -eq \"Marketing\"");
group.setMembershipRuleProcessingState("on");
Group result = graphClient.groups().post(group);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const group = {
    description: 'Marketing department folks',
    displayName: 'Marketing department',
    groupTypes: [
        'Unified',
        'DynamicMembership'
    ],
    mailEnabled: true,
    mailNickname: 'marketing',
    securityEnabled: false,
    membershipRule: 'user.department -eq \"Marketing\"',
    membershipRuleProcessingState: 'on'
};

await client.api('/groups')
	.post(group);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Group();
$requestBody->setDescription('Marketing department folks');
$requestBody->setDisplayName('Marketing department');
$requestBody->setGroupTypes(['Unified', 'DynamicMembership', 	]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('marketing');
$requestBody->setSecurityEnabled(false);
$requestBody->setMembershipRule('user.department -eq \"Marketing\"');
$requestBody->setMembershipRuleProcessingState('on');

$result = $graphServiceClient->groups()->post($requestBody)->wait();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

PowerShell

Import-Module Microsoft.Graph.Groups

$params = @{
	description = "Marketing department folks"
	displayName = "Marketing department"
	groupTypes = @(
	"Unified"
"DynamicMembership"
)
mailEnabled = $true
mailNickname = "marketing"
securityEnabled = $false
membershipRule = "user.department -eq "Marketing""
membershipRuleProcessingState = "on"
}

New-MgGroup -BodyParameter $params

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Group(
	description = "Marketing department folks",
	display_name = "Marketing department",
	group_types = [
		"Unified",
		"DynamicMembership",
	],
	mail_enabled = True,
	mail_nickname = "marketing",
	security_enabled = False,
	membership_rule = "user.department -eq \"Marketing\"",
	membership_rule_processing_state = "on",
)

result = await graph_client.groups.post(request_body)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

O pedido devolve um código de 201 Created resposta e o objeto de grupo recém-criado no corpo da 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": "6f7cd676-5445-47c4-9c2b-c47da4671da2",
    "createdDateTime": "2023-01-20T07:00:31Z",
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mail": "marketing@contoso.com",
    "mailEnabled": true,
    "mailNickname": "marketing",
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "On"
}

Outras definições de grupo

Pode configurar outras definições para grupos, tais como:

Configuração	Aplicável a
Expiração do grupo	Grupos do Microsoft 365
Configurações de grupo	Grupos do Microsoft 365
Definições de sincronização no local	Segurança e Grupos do Microsoft 365

Limitações de pesquisa de grupos para convidados em organizações

As aplicações podem procurar grupos no diretório de uma organização ao consultar o /groups recurso (por exemplo, https://graph.microsoft.com/beta/groups). Esta capacidade está disponível para administradores e membros, mas não para convidados.

Os convidados, consoante as permissões concedidas à aplicação, podem ver o perfil de um grupo específico (por exemplo, https://graph.microsoft.com/beta/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc). No entanto, não podem executar consultas no /groups recurso que devolvem vários resultados.

Geralmente, os membros têm acesso mais amplo aos recursos do grupo, enquanto os convidados têm permissões restritas, limitando o acesso a determinadas funcionalidades do grupo. Para obter mais informações, veja Comparar permissões predefinidas de membro e convidado.

Com as permissões adequadas, as aplicações podem aceder a perfis de grupo através de propriedades de navegação, tais como /groups/{id}/members.

Licenciamento com base em grupo

O licenciamento baseado em grupos permite-lhe atribuir uma ou mais licenças de produto a um grupo de Microsoft Entra. Os membros do grupo, incluindo quaisquer novos membros, herdam automaticamente as licenças. Quando os membros saem do grupo, as respetivas licenças são removidas automaticamente. Esta funcionalidade só está disponível para grupos de segurança e Grupos do Microsoft 365 com securityEnabled definido como true.

Para obter mais informações, veja O que é o licenciamento baseado em grupos no Microsoft Entra ID?.

Propriedades armazenadas fora do arquivo de dados main

A maioria dos dados de recursos de grupo é armazenada em Microsoft Entra ID, mas algumas propriedades, como autoSubscribeNewMembers e allowExternalSenders, são armazenadas no Microsoft Exchange. Estas propriedades não podem ser incluídas no mesmo corpo do pedido Criar ou Atualizar que outras propriedades do grupo.

Além disso, as propriedades armazenadas fora do arquivo de dados main não são suportadas para controlo de alterações. As alterações a estas propriedades não aparecem nas respostas de consulta delta.

As seguintes propriedades de grupo são armazenadas fora do arquivo de dados main:
accessType, allowExternalSenders, autoSubscribeNewMembers, cloudLicensing, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, membershipRuleProcessingStatus, isArchived.

Casos de utilização comuns para a API de grupos

A API de grupos do Microsoft Graph suporta estas operações comuns:

Caso de uso	Operações de API
Crie e gerencie grupos	Criar, listar, atualizar e eliminar
Gerenciar a associação a um grupo	Listar membros, adicionar membro e remover membro
Gerir a propriedade do grupo	Listar proprietários, adicionar proprietário e remover proprietário
Funcionalidade de grupo do Microsoft 365	Gerir conversações, eventos de calendário, blocos de notas do OneNote e ativar para o Teams

Microsoft Entra funções para gerir grupos

Para gerir grupos, o utilizador com sessão iniciada tem de ter as permissões adequadas do Microsoft Graph e ser-lhe atribuída uma função de Microsoft Entra suportada.

As funções com menos privilégios para gerir grupos são:

• Escritores de diretório
• Administrador de Grupos
• Administrador do usuário

Para obter mais informações, veja Funções com menos privilégios para gerir grupos.

Próxima etapa

Começar a trabalhar com grupos