Trabalhando com grupos no Microsoft Graph

Grupos são coleções de entidades de segurança com acesso compartilhado a recursos em serviços Microsoft ou no seu aplicativo. Diferentes entidades de segurança, como usuários, outros grupos, dispositivos e aplicativos, podem fazer parte de grupos. O uso de grupos ajuda você a evitar trabalhar com entidades de segurança individuais e simplifica o gerenciamento do acesso aos seus recursos.

O Microsoft Graph expõe a API de grupos para criar e gerenciar diferentes tipos de grupos e funcionalidades de grupo.

Observação

1. Os grupos só podem ser criados por meio de contas corporativas ou de estudante. As contas pessoais da Microsoft não são compatíveis com grupos.
2. Todas as operações relacionadas a grupos no Microsoft Graph exigem autorização do administrador.

Tipos de grupo no Microsoft Entra ID e no Microsoft Graph

Microsoft Entra ID dá suporte aos seguintes tipos de grupos.

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

Observação

A Microsoft também suporta grupos dinâmicos de distribuição que não podem ser gerenciados ou recuperados através do Microsoft Graph.

Somente grupos de segurança e do Microsoft 365 podem ser gerenciados por meio da API de grupos do Microsoft Graph. Grupos de distribuição e habilitados para email são somente leitura por meio do Microsoft Graph.

No Microsoft Graph, o tipo de grupo pode ser identificado pelas configurações de suas propriedades groupType, mailEnabled e securityEnabled conforme indicado na tabela abaixo.

Tipo	groupType	mailEnabled	securityEnabled	Criado e gerenciado através da API de grupos
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
Grupos de distribuição	[]	true	false	Não

Para obter mais informações sobre grupos, consulte as seções abaixo. Para obter mais informações sobre grupos em Microsoft Entra ID, consulte comparar grupos em Microsoft Entra ID.

Grupos do Microsoft 365

O diferencial dos grupos da Microsoft 365 está na natureza cooperativa, perfeito para as pessoas que trabalham em conjunto em um projeto ou uma equipe. Eles são criados com recursos que os membros do grupo compartilham, incluindo:

• Conversas do Outlook
• Calendário do Outlook
• Arquivos do SharePoint
• Bloco de anotações do OneNote
• Site de equipe do SharePoint
• Planos do Planner
• Gerenciamento de dispositivos do Microsoft Intune

O objeto JSON a seguir mostra um exemplo de representação de um grupo quando você chama a API de grupos do Microsoft Graph.

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",
    "deletedDateTime": null,
    "classification": "MBI",
    "createdDateTime": "2016-08-23T14:46:56Z",
    "description": "This is a group in Outlook",
    "displayName": "OutlookGroup101",
    "groupTypes": [
        "Unified"
    ],
    "mail": "outlookgroup101@service.microsoft.com",
    "mailEnabled": true,
    "mailNickname": "outlookgroup101",
    "preferredLanguage": null,
    "proxyAddresses": [
        "smtp:outlookgroup101@contoso.com",
        "SMTP:outlookgroup101@service.microsoft.com"
    ],
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

Para saber mais sobre os grupos do Microsoft 365, confira Visão geral dos grupos do Microsoft 365 no Microsoft Graph.

Configurações para grupos do Microsoft 365

Além de configurar as propriedades de grupo padrão, você também pode configurar as seguintes configurações para grupos do Microsoft 365.

• Expiração de grupo
• Configurações de grupo, como se o grupo pode ter convidados como membros, quem tem permissão para criar grupos, palavras permitidas em nomes de grupo e assim por diante.

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

Os grupos de segurança servem para controlar o acesso do usuário aos recursos. Ao verificar se um usuário faz parte de um grupo de segurança, seu aplicativo pode tomar decisões de autorização quando esse usuário tentar acessar alguns recursos seguros do seu aplicativo. Os grupos de segurança podem ter usuários, outros grupos de segurança, dispositivos e entidades de serviço como membros.

Grupos de segurança habilitados para email são usados da mesma forma que grupos de segurança, mas podem ser usados para enviar emails para membros do grupo. Os grupos de segurança habilitados para email não podem ser criados ou atualizados por meio da API; em vez disso, eles são somente leitura. Saiba mais no artigo Gerenciar de grupos de segurança habilitados para email no Exchange.

O objeto JSON a seguir mostra uma representação de exemplo de um grupo de segurança quando você chama a API de grupos do Microsoft Graph.

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

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2016-07-20T09:21:23Z",
    "description": "This group is a Security Group",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "",
    "preferredLanguage": null,
    "proxyAddresses": [],
    "securityEnabled": true
}

Associação a um grupo

A associação a grupos pode ser atribuída estaticamente ou dinâmica. 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

O Microsoft 365 e os grupos de segurança podem ter regras dinâmicas de associação que adicionam ou removem membros automaticamente do grupo com base nas propriedades da entidade. Por exemplo, um grupo "Funcionários de marketing" pode definir uma regra de associação dinâmica que apenas os usuários com suas propriedades de departamento definidas como "Marketing" podem ser membros do grupo. Nesse caso, todos os usuários que saem do departamento são automaticamente removidos do grupo.

Somente usuários e dispositivos têm suporte como membros em grupos de associação dinâmica. Você pode criar um grupo de associação dinâmica para dispositivos ou usuários, mas não ambos.

As regras de associação dinâmica são especificadas através da propriedade membershipRule durante a criação do grupo. Uma única expressão segue essa sintaxe: Property Operator Value.

• O Property é definido seguindo esta sintaxe: object.property. Por exemplo user.department ou device.accountEnabled.
• A sintaxe de regra dá suporte a vários operadores. Para obter mais informações, consulte Operadores de expressão com suporte.
• Uma Value cadeia de caracteres do tipo deve ser incluída em aspas duplas ("). Você deve usar um backslash para escapar de todas aspas duplas dentro de aspas duplas. Esse requisito não se aplica ao usar o construtor de regras no centro de administração do Microsoft Entra porque a expressão não está entre aspas duplas.

O exemplo a seguir mostra uma regra completa.

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

Você pode combinar várias expressões em uma regra usando os andoperadores , ore not .

A propriedade groupType também deve incluir o "DynamicMembership" valor na coleção. A regra de associação dinâmica pode ser ativada ou desativada através da propriedade membershipRuleProcessingState. Você pode atualizar um grupo com associação atribuída para ter associação dinâmica.

O exemplo de solicitação de a seguir cria um novo grupo do Microsoft 365 que só pode incluir funcionários no departamento de Marketing.

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

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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) 

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

from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group

graph_client = GraphServiceClient(credentials, scopes)

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

Para saber mais sobre como formular regras de associação, consulte Regras dinâmicas de associação para grupos em Microsoft Entra ID.

Observação

As regras de associação dinâmica exigem que o locatário tenha pelo menos uma licença P1 Microsoft Entra ID para cada usuário exclusivo que seja membro de um ou mais grupos dinâmicos.

Outros tipos de grupos

Os grupos do Microsoft 365 no Yammer são usados para facilitar a colaboração de usuários por meio de postagens no Yammer. Esse tipo de grupo pode ser retornado por meio de uma solicitação de leitura, mas as postagens nele não podem ser acessadas por meio da API. Quando as postagens e os feeds de conversas do Yammer são habilitados em um grupo, as conversas padrão em grupo do Microsoft 365 são desabilitadas. Saiba mais em Documentos de API do desenvolvedor do Yammer.

Limitações de pesquisas em grupo para usuários convidados em organizações

Os recursos de pesquisa de grupo permitem que o aplicativo pesquise por grupos no diretório de uma organização executando consultas no /groups recurso (por exemplo, https://graph.microsoft.com/v1.0/groups). Administradores e usuários que são membros têm essa funcionalidade; no entanto, os usuários convidados não.

Se o usuário conectado for um usuário convidado, dependendo das permissões concedidas a um aplicativo, ele poderá ler o perfil de um grupo específico (por exemplo, https://graph.microsoft.com/v1.0/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc); no entanto, ele não poderá realizar consultas em relação ao recurso /groups que potencialmente retorna mais de um único recurso.

Com as permissões apropriadas, o aplicativo pode ler os perfis dos grupos obtidos seguindo os links nas propriedades de navegação; por exemplo, /groups/{id}/members.

Para obter mais informações sobre o que os usuários convidados podem fazer com os grupos, consulte Comparar permissões padrão de membros e convidados.

Licenciamento com base em grupo

Você pode usar o licenciamento baseado em grupo para atribuir uma ou mais licenças de produto a um grupo de Microsoft Entra. Microsoft Entra ID garante que as licenças sejam atribuídas a todos os membros do grupo. Todos os novos membros que ingressarem no grupo receberão as licenças apropriadas. Quando eles deixarem o grupo, essas licenças serão removidas. O recurso só pode ser usado com os grupos de segurança e grupos do Microsoft 365 que possuam securityEnabled=TRUE. Para saber mais sobre licenciamento baseado em grupo, consulte O que é licenciamento baseado em grupo em Microsoft Entra ID?.

Casos de uso comuns

Usando o Microsoft Graph, você pode executar as seguintes operações comuns nos grupos.

Casos de uso	Recursos REST	Confira também
Criar grupos, gerenciar as características do grupo
Criar novos grupos, obter os grupos existentes, atualizar as propriedades nos grupos e excluir grupos. Atualmente, somente os grupos de segurança e grupos no Outlook podem ser criados por meio da API.	grupo	Criar novos grupos Listar grupos Atualizar grupos Excluir grupos
Gerenciar a associação a um grupo
Listar os membros de um grupo e adicionar ou remover membros.	usuário grupo	Listar membros Adicionar membro Remover membro
Determinar se um usuário faz parte de um grupo, acessar todos os grupos do qual o usuário faz parte.	usuário group servicePrincipal orgContact	Verificar grupos de membros Obter grupos de membros
Listar os proprietários de um grupo e adicionar ou remover proprietários.	usuário grupo	Listar proprietários Adicionar membro Remover membro