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 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
oudevice.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 and
operadores , or
e 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"
}
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?.
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.