Trabalhando com grupos no Microsoft Graph

Artigo
12/28/2024

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 o tipo de recurso de grupo e as respetivas APIs associadas para criar e gerir diferentes tipos de grupos e funcionalidades de grupo.

Observação

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.
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 suporta os 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 de distribuição dinâmicos que não podem ser geridos ou obtidos através do Microsoft Graph.

No Microsoft Graph, o tipo de grupo pode ser identificado pelas definições das respetivas propriedades groupTypes, mailEnabled e securityEnabled . A tabela seguinte indica como diferenciar os grupos pelas respetivas definições e se os tipos de grupo podem ser geridos através das APIs de grupos do Microsoft Graph.

Tipo	groupTypes	mailEnabled	securityEnabled	Criadas e geridas através das APIs 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; só de leitura através do Microsoft Graph
Grupos de distribuição	`[]`	`true`	`false`	Não; só de leitura através do Microsoft Graph

Para obter mais informações sobre grupos no Microsoft Entra ID, veja Comparar grupos no 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, consulte Descriçã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 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.

Os grupos de segurança com capacidade de correio são utilizados da mesma forma que os grupos de segurança, mas podem ser utilizados para enviar e-mails a 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. Para mais informações, consulte Gerenciar grupos de segurança habilitados para email.

O seguinte objeto JSON mostra uma representação de exemplo de um grupo de segurança quando 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 de associação dinâmicas que adicionam ou removem automaticamente membros do grupo com base nas propriedades do principal. 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. Neste caso, todos os utilizadores que saírem do departamento são automaticamente removidos do grupo.

Apenas os utilizadores e dispositivos são suportados como membros em grupos de membros dinâmicos. Pode criar um grupo de membros dinâmico para dispositivos ou utilizadores, mas não para 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 esta sintaxe: Property Operator Value.

O Property é definido seguindo esta sintaxe: object.property. Por exemplo: user.department ou device.accountEnabled.
A sintaxe da regra suporta vários operadores. Para obter mais informações, veja Operadores de expressão suportados.
Um Value do tipo Cadeia tem de estar entre aspas duplas ("). Tem de utilizar uma barra invertida para escapar a aspas duplas entre aspas duplas. Este requisito não se aplica ao utilizar o construtor de regras no centro de administração do Microsoft Entra porque a expressão não está entre aspas duplas.

O exemplo seguinte mostra uma regra completa.

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

Pode combinar múltiplas expressões numa regra com os andoperadores , ore not .

A propriedade groupTypes também tem de incluir o "DynamicMembership" valor na coleção. A regra de associação dinâmica pode ser ativada ou desativada através da propriedade membershipRuleProcessingState. 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.

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.



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.



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

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

Para saber mais sobre a formulação de regras de associação, veja Regras de associação dinâmicas para grupos no Microsoft Entra ID.

Observação

As regras de associação dinâmica requerem que o inquilino tenha, pelo menos, uma licença P1 Microsoft Entra ID para cada utilizador 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.

Definições adicionais para segurança e grupos do Microsoft 365

Além de configurar as propriedades no recurso de grupo, também pode configurar as seguintes definições para grupos.

Setting	Aplicável a
Expiração do grupo	Grupos do Microsoft 365
Definições de grupo, como se o grupo pode ter convidados como membros, palavras permitidas em nomes de grupos, quem tem permissão para criar grupos, etc.	Grupos do Microsoft 365
Definições para sincronizar grupos no local com a cloud, como se a repetição de escrita está ativada	Segurança e grupos do Microsoft 365

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

As capacidades de pesquisa de grupos permitem que a aplicação procure quaisquer grupos no diretório de uma organização ao realizar consultas no /groups recurso (por exemplo, https://graph.microsoft.com/v1.0/groups). Tanto os administradores como os utilizadores que são membros têm esta capacidade; no entanto, os utilizadores 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

Pode utilizar o licenciamento baseado em grupos para atribuir uma ou mais licenças de produto a um grupo de Microsoft Entra e, em seguida, as licenças são herdadas pelos membros do grupo e automaticamente por quaisquer novos membros. Quando os membros saem do grupo, essas licenças são removidas. A funcionalidade só pode ser utilizada com grupos de segurança e grupos do Microsoft 365 que tenham securityEnabled definido como true.

Para saber mais sobre o licenciamento baseado em grupos, veja O que é o licenciamento baseado em grupos no Microsoft Entra ID?.

Propriedades armazenadas fora do arquivo de dados main

Embora os dados de recursos do grupo estejam armazenados principalmente em Microsoft Entra ID, algumas das suas propriedades, como autoSubscribeNewMembers e allowExternalSenders, são armazenadas no Microsoft Exchange. Na maioria das instâncias, não pode especificar estas propriedades no mesmo corpo do pedido Criar ou Atualizar que outras propriedades do grupo.

As propriedades armazenadas fora do arquivo de dados main também não são suportadas como parte do controlo de alterações. Por conseguinte, uma alteração a qualquer uma destas propriedades não resulta na apresentação de um objeto na resposta da consulta delta.

As seguintes propriedades no objeto 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 uso comuns

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

Casos de uso	Operações de API
Criar grupos, gerenciar as características do grupo
Criar novos grupos, obter os grupos existentes, atualizar as propriedades nos grupos e excluir grupos.	Criar novos grupos Listar grupos Atualizar grupos Excluir grupos Renovar grupos que estão prestes a expirar Restaurar grupos eliminados do Microsoft 365
Gerir a associação e a propriedade do grupo
Listar os membros de um grupo e adicionar ou remover membros.	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.	Verificar grupos de membros Obter grupos de membros
Listar os proprietários de um grupo e adicionar ou remover proprietários.	Listar proprietários Adicionar proprietário Remover proprietário
Funcionalidade de grupo para aplicações do Microsoft 365
Gerir conversações de grupo	Criar, obter ou eliminar
Agendar e gerir eventos de calendário num calendário de grupo	Criar, listar, obter, atualizar, eliminar
Gerir blocos de notas do OneNote para um grupo	Criar, listar
Ativar um grupo Microsoft para o Microsoft Teams	Create

Microsoft Entra funções para gerir grupos

Para gerir grupos em cenários delegados, tem de ser concedida à aplicação as permissões adequadas do Microsoft Graph e o utilizador com sessão iniciada tem de ter uma função de Microsoft Entra suportada.

As seguintes funções Microsoft Entra são as funções com menos privilégios para todas as operações de leitura e escrita em grupos através do Microsoft Graph, exceto para grupos atribuíveis a funções. A função com menos privilégios para gerir grupos atribuíveis a funções é Administrador de Funções Privilegiadas.

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

Para obter um resumo das funções de administrador com menos privilégios para diferentes tarefas relacionadas com grupos, veja Funções com menos privilégios para gerir grupos.

Também pode criar funções personalizadas para tarefas relacionadas com grupos. Veja o Microsoft Entra referência de funções incorporadas para identificar permissões que começam com microsoft.directory/groups/ as quais inferem as tarefas específicas da permissão e crie uma função personalizada com as permissões selecionadas.

Próxima etapa

Começar a trabalhar com grupos

Partilhar via

Trabalhando com grupos no Microsoft Graph

Tipos de grupo no Microsoft Entra ID e no Microsoft Graph

Grupos do Microsoft 365

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

Associação a um grupo

Associação dinâmica

Outros tipos de grupos

Definições adicionais para segurança e grupos do Microsoft 365

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

Licenciamento com base em grupo

Propriedades armazenadas fora do arquivo de dados main

Casos de uso comuns

Microsoft Entra funções para gerir grupos

Próxima etapa

Comentários

Recursos adicionais