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

  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 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 Pode ser membro do grupo Pode ser membro do grupo
Grupo de segurança Pode ser membro do grupo Não pode ser membro do grupo
Grupo Microsoft 365 Não pode ser membro do grupo Não pode ser membro do grupo
Dispositivo Pode ser membro do grupo Não pode ser membro do grupo
Entidade de serviço Pode ser membro do grupo Não pode ser membro do grupo
Contatos organizacionais Pode ser membro do grupo Não pode ser membro do grupo

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

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.

Próxima etapa