Gerenciar grupos no Microsoft Graph

Os grupos no Microsoft Graph são contêineres para entidades de segurança, como usuários, dispositivos ou aplicativos que compartilham o acesso a recursos. Eles facilitam o gerenciamento de acesso agrupando entidades de segurança em vez de gerenciá-las individualmente.

O tipo de recurso de grupo no Microsoft Graph fornece APIs para criar e gerenciar tipos de grupo com suporte e suas funcionalidades.

Observação

Você só pode criar grupos usando contas corporativas ou de estudante. As contas pessoais da Microsoft não são compatíveis com grupos.
Todas as operações relacionadas ao grupo no Microsoft Graph precisam do consentimento do administrador.

Tipos de grupos com suporte no Microsoft Graph

O Microsoft Graph dá suporte a 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

Não há suporte para grupos dinâmicos de distribuição no Microsoft Graph.

A tabela a seguir mostra como identificar tipos de grupos usando suas propriedades e se eles podem ser gerenciados por meio da API de grupos do Microsoft Graph. Os principais diferenciais são os valores nas propriedades groupTypes, mailEnabled e securityEnabled de um grupo.

Tipo	groupTypes	mailEnabled	securityEnabled	Gerenciado via 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 (somente leitura)
Grupos de distribuição	`[]`	`true`	`false`	Não (somente leitura)

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

Grupos do Microsoft 365

Os Grupos do Microsoft 365 são projetados para colaboração e fornecem acesso a recursos compartilhados, como:

Conversas e calendário do Outlook.
Arquivos do SharePoint e site de equipe.
Bloco de anotações do OneNote.
Planos do Planner.
Gerenciamento de dispositivos do Intune.

Aqui está um exemplo de um grupo do Microsoft 365 no formato 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 os Grupos do Microsoft 365, consulte Visão geral dos 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. Elas podem incluir usuários, outros grupos, dispositivos e entidades de serviço.

Os grupos de segurança habilitados para email funcionam como grupos de segurança, mas também permitem a comunicação por email. Esses grupos são somente 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
}

Propriedade do grupo

Os grupos podem ter um ou mais proprietários que gerenciam o grupo. Os proprietários podem ser usuários ou entidades de serviço. É recomendável atribuir pelo menos dois proprietários a um grupo para garantir a continuidade.

Política de grupo sem proprietário

Quando um grupo perde seu único proprietário, ele se torna sem proprietário e não pode mais ser gerenciado com eficiência. Use o recurso ownerlessGroupPolicy para configurar uma política no nível do locatário que envia automaticamente emails de notificação acionáveis para membros ativos de grupos sem proprietário, solicitando-lhes que aceitem a propriedade. Os administradores podem configurar a duração da notificação, o número máximo de membros a serem notificados e controlar a qualificação de propriedade usando grupos de segurança. Para obter mais informações, consulte Obter ownerlessGroupPolicy e Criar ou atualizar ownerlessGroupPolicy.

Associação a um grupo

Os grupos podem ter associações estáticas ou dinâmicas. A associação dinâmica usa regras para adicionar ou remover membros automaticamente com base em suas 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

Associação dinâmica significa que as entidades de segurança são adicionadas ou removidas do grupo com base em suas propriedades. Por exemplo, um grupo pode ser definido para incluir todos os usuários no departamento de "Marketing". Quando um usuário é adicionado a esse departamento, ele é adicionado automaticamente ao grupo. Da mesma forma, se um usuário sair do departamento, ele será removido do grupo.

Somente usuários e dispositivos podem ser membros de um grupo dinâmico. A associação dinâmica requer uma licença P1 do Microsoft Entra ID para cada usuário exclusivo em um grupo dinâmico.

A regra de associação é definida usando a sintaxe de regra de grupo dinâmico do 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. Você pode atualizar um grupo de associação estática para associação dinâmica.

Exemplo de solicitação para criar um grupo dinâmico do Microsoft 365:

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"
}


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



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


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


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


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.


# 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.

A solicitação retorna 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 configurações de grupo

Você pode definir outras configurações para grupos, como:

Configuração	Descrição	Aplicável a
Expiração de grupo	Configure uma política de expiração para que os grupos do Microsoft 365 sejam excluídos automaticamente após um período especificado, a menos que sejam renovados.	Grupos do Microsoft 365
Configurações de grupo	Configure comportamentos para grupos usando modelos de configuração. Os modelos de configuração incluem: Group.Unified para configurações de grupo do Microsoft 365 (como políticas de nomenclatura, acesso de convidado e rótulos de confidencialidade), Group.Unified.Guest para configurações de convidado do Microsoft 365, Group.Security para configurações de grupo de segurança na nuvem (como habilitar rótulos de confidencialidade) e Group.Security.Policies para configurações de segurança na nuvem.	Grupos do Microsoft 365 e grupos de segurança de nuvem
Configurações de sincronização local	Defina as configurações de sincronização de diretório local.	Segurança e grupos do Microsoft 365

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

Os aplicativos podem pesquisar grupos no diretório de uma organização consultando o /groups recurso (por exemplo, https://graph.microsoft.com/v1.0/groups). Esse recurso está disponível para administradores e membros, mas não para convidados.

Os convidados, dependendo das permissões concedidas ao aplicativo, podem exibir o perfil de um grupo específico (por exemplo, https://graph.microsoft.com/v1.0/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc). No entanto, eles não podem executar consultas no /groups recurso que retornam vários resultados.

Os membros geralmente têm acesso mais amplo aos recursos do grupo, enquanto os convidados têm permissões restritas, limitando seu acesso a determinados recursos do grupo. Para obter mais informações, consulte Comparar permissões padrão de membro e convidado.

Com as permissões apropriadas, os aplicativos podem acessar perfis de grupo por meio de propriedades de navegação, como /groups/{id}/members.

Licenciamento com base em grupo

O licenciamento baseado em grupo permite que você atribua uma ou mais licenças de produto a um grupo do Microsoft Entra. Os membros do grupo, incluindo os novos membros, herdam automaticamente as licenças. Quando os membros deixam o grupo, suas licenças são removidas automaticamente. Esse recurso está disponível apenas para grupos de segurança e Grupos do Microsoft 365 com securityEnabled definido como true.

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

Propriedades armazenadas fora do repositório de dados principal

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

Além disso, as propriedades armazenadas fora do repositório de dados principal não têm suporte para controle de alterações. As alterações nessas propriedades não aparecem nas respostas de consulta delta.

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

Casos de uso comuns para a API de grupos

A API de grupos do Microsoft Graph dá suporte a estas operações comuns:

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

Funções do Microsoft Entra para gerenciar grupos

Para gerenciar grupos, o usuário conectado deve ter as permissões apropriadas do Microsoft Graph e ser atribuído a uma função do Microsoft Entra com suporte ou uma função personalizada com permissões com suporte. O Administrador de Grupos é a principal função para gerenciar grupos, mas outras funções, como Administrador de Usuários, Administrador do Exchange e Gravadores de Diretório , também podem gerenciar grupos com níveis variados de permissões.

As funções menos privilegiadas para o gerenciamento de grupos são:

Escritores de diretório
Administrador de grupos
Administrador do usuário

Para obter mais informações, consulte Funções menos privilegiadas para gerenciar grupos.

Próxima etapa

Começar a trabalhar com grupos

Confira também

Práticas recomendadas para gerenciar grupos na nuvem

Comentários

Esta página foi útil?

Last updated on 2026-08-24

Gerenciar grupos no Microsoft Graph

Tipos de grupos com suporte no Microsoft Graph

Grupos do Microsoft 365

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

Propriedade do grupo

Política de grupo sem proprietário

Associação a um grupo

Associação dinâmica

Outras configurações de grupo

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

Licenciamento com base em grupo

Propriedades armazenadas fora do repositório de dados principal

Casos de uso comuns para a API de grupos

Funções do Microsoft Entra para gerenciar grupos

Próxima etapa

Confira também

Comentários

Recursos adicionais