Compartir a través de

List groups

Espacio de nombres: microsoft.graph

Enumere todos los grupos disponibles en una organización, excepto los grupos de distribución dinámica. Para recuperar grupos de distribución dinámicos, use el Centro de administración de Exchange.

Esta operación devuelve de forma predeterminada solo un subconjunto de las propiedades de cada grupo. Estas propiedades predeterminadas se indican en la sección Propiedades. Para obtener propiedades que no se devuelven de forma predeterminada, realice una operación GET para el grupo y especifique las propiedades de una opción de consulta de OData $select. Las propiedades hasMembersWithLicenseErrors y isArchived son una excepción y no se devuelven en la consulta $select.

Nota: Esta solicitud puede tener retrasos de replicación para grupos que se crearon, actualizaron o eliminaron recientemente.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) GroupMember.Read.All Group.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Group.Read.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación GroupMember.Read.All Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, Group.ReadWrite.All

Solicitud HTTP

GET /groups

Parámetros de consulta opcionales

Este método admite los $countparámetros de consulta , $expand, $filter, $orderby$search, $selecty $top OData para ayudar a personalizar la respuesta. No se admite $skip. Los tamaños de página predeterminados y máximos son 100 y 999 objetos de grupo, respectivamente. Algunas consultas solo se admiten cuando se usa el encabezado ConsistencyLevel establecido en eventual y $count. Para obtener más información, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Para enumerar únicamente grupos de Microsoft 365 (también denominados grupos unificados), aplique un filtro en groupTypes:

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

El $searchparámetro de consulta admite la tokenización solo en los campos displayName y descripción y requiere el encabezado ConsistencyLevel. Los campos que no sean displayName y description se establecen de forma predeterminada en el $filterstartswith comportamiento.

Las propiedades de extensión también admiten parámetros de consulta como se indica a continuación:

Tipo de extensión Comentarios
Extensiones de esquema Solo se devuelve con $select.
Extensiones abiertas Solo se devuelve con $expand.
Extensiones de directorio Se devuelve de forma predeterminada.

Para más información sobre las opciones de consulta de OData, consulte Parámetros de consulta de OData. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Filtrar por tipos de grupo

Tipo de grupo Solicitud de API
Grupos de Microsoft 365 (unificado) GET/groups?$filter=groupTypes/any(c:c+eq+'Unified')
Grupos de seguridad GET/groups?$filter=mailEnabled eq false&securityEnabled eq true
Grupos de seguridad habilitados para correo OBTENER/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq true&$count=true **
Grupos de distribución OBTENER/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq false&$count=true **

** : este ejemplo solo se admite con funcionalidades de consulta avanzadas.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
ConsistencyLevel eventual. Este encabezado y $count son necesarios cuando se usa $search,o en un uso específico de $filter. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud para este método.

Respuesta

Si se ejecuta correctamente, este método devuelve un código de respuesta 200 OK y la colección de objetos group en el cuerpo de la respuesta. La respuesta incluye sólo las propiedades predeterminadas de cada grupo.

Ejemplos

Ejemplo 1: Obtener una lista de grupos

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/v1.0/groups

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad. Se devolverán las propiedades predeterminadas para cada grupo de una llamada real.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$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,
      "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": []
    }
  ]
}

Ejemplo 2: Obtener una lista filtrada de grupos

Esta solicitud que filtra la propiedad hasMembersWithLicenseErrors no admite la recuperación del recuento de objetos devueltos.

Solicitud

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

Respuesta

El siguiente es un ejemplo de respuesta que incluye solo las propiedades solicitadas.

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

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$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"
      }
   ]
}

Ejemplo 3: Obtener solo un recuento de grupos

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $count está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

893

Ejemplo 4: Usar $filter y $top para obtener un grupo con un nombre para mostrar que comience por 'a', incluido un recuento de los objetos devueltos

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual y la cadena de consulta $count=true porque la solicitud tiene los parámetros de consulta $orderby y $filter. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

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

Ejemplo 5: Use $search para obtener grupos con nombres para mostrar que contengan las letras "Video" o una descripción que contenga las letras "prod", incluido un recuento de objetos devueltos.

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $search está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$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"
      }
   ]
}

Ejemplo 6: Lista de grupos de seguridad dinámicos

Solicitud

En el ejemplo siguiente se muestra una solicitud que filtra por membershipRuleProcessingState para recuperar grupos dinámicos. También puede filtrar por las propiedades de groupTypes (es decir,$filter=groupTypes/any(s:s eq 'DynamicMembership')). Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual y la cadena de consulta $count=true porque la solicitud usa el operador not del parámetro de consulta $filter. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

GET https://graph.microsoft.com/v1.0/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
ConsistencyLevel: eventual

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$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"
        }
    ]
}

Ejemplo 7: Enumerar los grupos con licencias y obtener los miembros del grupo

Solicitud

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$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": []
    }
  ]
}