Comentários Editar

Listar grupos

  • Artigo
  • 18 minutos para o fim da leitura

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 de versão.

Liste todos os grupos disponíveis em uma organização, excluindo grupos dinâmicos de distribuição. 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.

Permissões

Uma das seguintes permissões é obrigatória para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

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

Solicitação HTTP

GET /groups

Parâmetros de consulta opcionais

Este método suporta aos parâmetros de consulta $count, $expand, $filter, $orderBy, $search, $select, e $top OData para ajudar a personalizar a resposta. 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, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

Para listar apenas grupos do Microsoft 365 (também conhecidos como 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. Qualquer campo além de displayName e description é padrão para o comportamento$filter``startswith.

Para obter mais informações sobre as opções de consulta OData, veja Parâmetros de consulta OData. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

Recuperar extensões e dados associados

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.

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório.
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 o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

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

Este é um exemplo de solicitação.

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

Resposta

Este é um exemplo de resposta.

Observação: o objeto de resposta mostrado aqui pode ser reduzido para facilitar a leitura. 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.onmicrosoft.com",
            "SMTP:golfassist@contoso.com"
         ],
         "renewedDateTime":"2018-12-22T02:21:05Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "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.onmicrosoft.com",
            "SMTP:golftalk@contoso.com"
         ],
         "renewedDateTime":"2018-11-19T20:29:40Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "theme":null,
         "visibility":null,
         "onPremisesProvisioningErrors":[
         ]
      }
   ]
}

Exemplo 2: Obter uma lista filtrada de grupos, incluindo a contagem de objetos retornados

Solicitação

Este é um exemplo de 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 o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

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=true&$filter=hasMembersWithLicenseErrors+eq+true&$select=id,displayName
ConsistencyLevel: eventual

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)",
   "@odata.count":2,
   "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

Este é um exemplo de 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 o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

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

Este é um exemplo de 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

Este é um exemplo de 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 o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

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

Este é um exemplo de 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 de exibição que contenham as letras 'Vídeo', incluindo uma contagem de objetos retornados

Solicitação

Este é um exemplo de 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 o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

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"&$count=true
ConsistencyLevel: eventual

Resposta

Este é um exemplo de 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"
      }
   ]
}

Exemplo 6: Utilize $search para obter grupos com nomes de exibição que contenham as letras 'Vídeo' ou uma descrição que contenha as letras 'prod', incluindo uma contagem de objetos retornados

Solicitação

Este é um exemplo de 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 o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

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

Este é um exemplo de 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 7: listar grupos dinâmicos

Solicitação

A seguir se encontra um exemplo da solicitação filtrada por membershipRuleProcessingState para recuperar 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 ConsistencyLevel definido 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 o uso de ConsistencyLevel e $count, consulte Funcionalidades avançadas de consulta nos objetos de diretório do Microsoft Azure AD.

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

Este é um exemplo de 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 8: listar todos os grupos com licenças

Solicitação

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

Resposta

Este é um exemplo de resposta.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups(id,assignedLicenses)",
    "value": [
        {
            "id": "5caf712c-8483-4b3d-8384-d8da988c0ca4",
            "assignedLicenses": [
                {
                    "disabledPlans": [],
                    "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
                }
            ]
        },
        {
            "id": "aae8ec2a-5a08-4013-ae70-fafbb5c20de1",
            "assignedLicenses": [
                {
                    "disabledPlans": [
                        "7547a3fe-08ee-4ccb-b430-5077c5041653"
                    ],
                    "skuId": "18181a46-0d4e-45cd-891e-60aabd171b4e"
                }
            ]
        },
        {
            "id": "e55bdaa0-e104-479a-979e-b0457fff6380",
            "assignedLicenses": [
                {
                    "disabledPlans": [
                        "7547a3fe-08ee-4ccb-b430-5077c5041653"
                    ],
                    "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
                }
            ]
        }
    ]
}