Compartilhar via


Listar grupos

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Liste todos os grupos disponíveis numa organização, excluindo grupos de distribuição dinâmicos. Para recuperar grupos dinâmicos de distribuição, use o Centro de administração do Exchange.

Esta operação retorna, por padrão, apenas um subconjunto das propriedades mais usadas de cada grupo. Essas propriedades padrão estão listadas na seção Propriedades. Para obter propriedades não retornadas por padrão, execute uma operação GET para o grupo e especifique as propriedades em uma opção de consulta $select do OData. As propriedades hasMembersWithLicenseErrors e isArchived são uma exceção e não são retornadas na consulta $select.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante) GroupMember.Read.All Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Group.Read.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application GroupMember.Read.All Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, Group.ReadWrite.All

Solicitação HTTP

GET /groups

Parâmetros de consulta opcionais

Este método suporta os $countparâmetros de consulta , $expand, $filter$orderby, $search, $select, e $topOData para ajudar a personalizar a resposta. $skip não é compatível. Os tamanhos de página padrão e máximo são 100 e 999 objetos de grupo, respectivamente. Algumas consultas são suportadas somente quando se usa o cabeçalho ConsistencyLevel definido como eventual e $count. Para obter mais informações, veja Capacidades avançadas de consulta em objetos de diretório.

Para listar apenas grupos do Microsoft 365 (grupos unificados), aplique um filtro em groupTypes:

GET https://graph.microsoft.com/beta/groups?$filter=groupTypes/any(c:c+eq+'Unified')

O $search parâmetro de consulta suporta a tokenização apenas nos campos displayName e description e requer o cabeçalho ConsistencyLevel. Campos que não displayName e descrição predefinidos para $filterstartsWith comportamento.

As propriedades da extensão também suportam parâmetros de consulta da seguinte forma:

Tipo de extensão Comentários
Extensões de esquema Retornado somente com $select.
Extensões abertas Retornado somente com $expand.
Extensões de diretório Retornado por padrão.

Para obter mais informações sobre as opções de consulta OData, veja Parâmetros de consulta OData. Para obter mais informações sobre a utilização de ConsistencyLevel e $count, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Filtrar por tipos de grupo

Tipo de grupo Pedido de API
Grupos do Microsoft 365 (unificados) OBTER/groups?$filter=groupTypes/any(c:c+eq+'Unified')
Grupos de segurança OBTER/groups?$filter=mailEnabled eq false&securityEnabled eq true
Grupos de segurança habilitados para email OBTER/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq true&$count=true **
Grupos de distribuição OBTER/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq false&$count=true **

** : este exemplo só é suportado com capacidades de consulta avançadas.

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
ConsistencyLevel eventualmente. Este cabeçalho e $count são necessários quando se utiliza $search, ou em uso específico de $filter. Para obter mais informações sobre a utilização de ConsistencyLevel e $count, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Corpo da solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se bem-sucedido, este método retorna um código de resposta 200 OK e uma coleção de objetos group no corpo da resposta. A resposta inclui somente as propriedades padrão de cada grupo.

Exemplos

Exemplo 1: Obter uma lista de grupos

Solicitação

O exemplo a seguir mostra uma solicitação.

GET https://graph.microsoft.com/beta/groups

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade. Todas as propriedades padrão são retornadas para cada grupo em uma chamada real.

HTTP/1.1 200 OK
Content-type: application/json

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
   "value":[
      {
         "id":"45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
         "deletedDateTime":null,
         "classification":null,
         "createdDateTime":"2018-12-22T02:21:05Z",
         "description":"Self help community for golf",
         "displayName":"Golf Assist",
         "expirationDateTime":null,
         "groupTypes":[
            "Unified"
         ],
         "isAssignableToRole":null,
         "mail":"golfassist@contoso.com",
         "mailEnabled":true,
         "mailNickname":"golfassist",
         "membershipRule":null,
         "membershipRuleProcessingState":null,
         "onPremisesLastSyncDateTime":null,
         "onPremisesSecurityIdentifier":null,
         "onPremisesSyncEnabled":null,
         "preferredDataLocation":"CAN",
         "preferredLanguage":null,
         "proxyAddresses":[
            "smtp:golfassist@contoso.com",
            "SMTP:golfassist@contoso.com"
         ],
         "renewedDateTime":"2018-12-22T02:21:05Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "serviceProvisioningErrors": [
         ],
         "theme":null,
         "visibility":"Public",
         "onPremisesProvisioningErrors":[
         ]
      },
      {
         "id":"d7797254-3084-44d0-99c9-a3b5ab149538",
         "deletedDateTime":null,
         "classification":null,
         "createdDateTime":"2018-11-19T20:29:40Z",
         "description":"Talk about golf",
         "displayName":"Golf Discussion",
         "expirationDateTime":null,
         "groupTypes":[
         ],
         "isAssignableToRole":null,
         "mail":"golftalk@contoso.com",
         "mailEnabled":true,
         "mailNickname":"golftalk",
         "membershipRule":null,
         "membershipRuleProcessingState":null,
         "onPremisesLastSyncDateTime":null,
         "onPremisesSecurityIdentifier":null,
         "onPremisesSyncEnabled":null,
         "preferredDataLocation":"CAN",
         "preferredLanguage":null,
         "proxyAddresses":[
            "smtp:golftalk@contoso.com",
            "SMTP:golftalk@contoso.com"
         ],
         "renewedDateTime":"2018-11-19T20:29:40Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "serviceProvisioningErrors": [
         ],
         "theme":null,
         "visibility":null,
         "onPremisesProvisioningErrors":[
         ]
      }
   ]
}

Exemplo 2: Obter uma lista filtrada de grupos

Este pedido que filtra contra a propriedade hasMembersWithLicenseErrors não suporta a obtenção da contagem de objetos devolvidos.

Solicitação

GET https://graph.microsoft.com/beta/groups?$filter=hasMembersWithLicenseErrors+eq+true&$select=id,displayName

Resposta

Veja a seguir o exemplo de uma resposta que inclui apenas as propriedades solicitadas.

HTTP/1.1 200 OK
Content-type: application/json

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups(id,displayName)",
   "value":[
      {
         "id":"11111111-2222-3333-4444-555555555555",
         "displayName":"Contoso Group 1"
      },
      {
         "id":"22222222-3333-4444-5555-666666666666",
         "displayName":"Contoso Group 2"
      }
   ]
}

Exemplo 3: Obter apenas uma contagem de grupos

Solicitação

O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual porque $count está na solicitação. Para obter mais informações sobre a utilização de ConsistencyLevel e $count, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory B2C.

GET https://graph.microsoft.com/beta/groups/$count
ConsistencyLevel: eventual

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: text/plain

893

Exemplo 4: Utilize $filter e $top para obter um grupo com um nome de exibição que comece com 'a', incluindo uma contagem de objetos retornados

Solicitação

O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual e a cadeia de caracteres de consulta $count=true porque a solicitação tem os parâmetros de consulta $orderby e $filter. Para obter mais informações sobre a utilização de ConsistencyLevel e $count, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory B2C.

GET https://graph.microsoft.com/beta/groups?$filter=startswith(displayName, 'a')&$count=true&$top=1&$orderby=displayName
ConsistencyLevel: eventual

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
   "@odata.count":1,
   "value":[
      {
         "displayName":"a",
         "mailNickname":"a241"
      }
   ]
}

Exemplo 5: Utilize $search para obter grupos com nomes a apresentar que contenham as letras "Vídeo" ou uma descrição que contenha as letras "prod", incluindo uma contagem de objetos devolvidos

Solicitação

O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual porque $search está na solicitação. Para obter mais informações sobre a utilização de ConsistencyLevel e $count, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory B2C.

GET https://graph.microsoft.com/beta/groups?$search="displayName:Video" OR "description:prod"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
   "@odata.count":1396,
   "value":[
      {
         "displayName":"SFA Videos",
         "mail":"SFAVideos@service.contoso.com",
         "mailNickname":"SFAVideos"
      },
      {
         "description":"Video Production",
         "displayName":"Video Production",
         "mail":"videoprod@service.contoso.com",
         "mailNickname":"VideoProduction"
      }
   ]
}

Exemplo 6: Listar grupos dinâmicos

Solicitação

O exemplo seguinte mostra um pedido que filtra por membershipRuleProcessingState para obter grupos dinâmicos. Você também pode filtrar pelas propriedades groupTypes (ou seja, $filter=groupTypes/any(s:s eq 'DynamicMembership')). Essa solicitação requer o cabeçalho ConsistencyLeveldefinido como eventual e a $count=true cadeia de caracteres de consulta pois a solicitação usa o not operador do $filter parâmetro de consulta. Para obter mais informações sobre a utilização de ConsistencyLevel e $count, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory B2C.

GET https://graph.microsoft.com/beta/groups?$filter=mailEnabled eq false and securityEnabled eq true and NOT(groupTypes/any(s:s eq 'Unified')) and membershipRuleProcessingState eq 'On'&$count=true&$select=id,membershipRule,membershipRuleProcessingState

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups(id,membershipRule,membershipRuleProcessingState)",
    "@odata.count": 1,
    "value": [
        {
            "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/e9f4a701-e7b5-4401-a0ca-5bd5f3cdcf4b/Microsoft.DirectoryServices.Group",
            "id": "e9f4a701-e7b5-4401-a0ca-5bd5f3cdcf4b",
            "membershipRule": "(user.userType -contains \"Guest\" and user.accountEnabled -eq true) or (user.city -eq \"Nairobi\")",
            "membershipRuleProcessingState": "On"
        }
    ]
}

Exemplo 7: Listar todos os grupos com licenças e obter os membros do grupo

Solicitação

GET https://graph.microsoft.com/beta/groups?$select=id,assignedLicenses&$filter=assignedLicenses/any()&$expand=members($select=id,displayName)

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups(id,assignedLicenses,members())",
  "value": [
    {
      "id": "5caf712c-8483-4b3d-8384-d8da988c0ca4",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
        }
      ],
      "members": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "0952e4c8-432f-4950-a65c-769c45993527"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49e373b6-4717-40c6-ad43-843c45a258f0"
        }
      ]
    },
    {
      "id": "aae8ec2a-5a08-4013-ae70-fafbb5c20de1",
      "assignedLicenses": [
        {
          "disabledPlans": [
            "7547a3fe-08ee-4ccb-b430-5077c5041653"
          ],
          "skuId": "18181a46-0d4e-45cd-891e-60aabd171b4e"
        }
      ],
      "members": []
    }
  ]
}