List groupsList groups

Espacio de nombres: microsoft.graphNamespace: microsoft.graph

Importante

Las API de la /beta versión de Microsoft Graph están sujetas a cambios.APIs under the /beta version in Microsoft Graph are subject to change. No se admite el uso de estas API en aplicaciones de producción.Use of these APIs in production applications is not supported. Para determinar si una API está disponible en v1.0, usa el selector de versiones.To determine whether an API is available in v1.0, use the Version selector.

Enumera todos los grupos en una organización, incluidos entre otros los grupos de Microsoft 365.List all the groups in an organization, including but not limited to Microsoft 365 groups.

Esta operación devuelve de forma predeterminada solo un subconjunto de las propiedades más utilizadas de cada grupo.This operation returns by default only a subset of the more commonly used properties for each group. Estas propiedades predeterminadas se indican en la sección Propiedades.These default properties are noted in the Properties section. 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.To get properties that are not returned by default, do a GET operation for the group and specify the properties in a $select OData query option. La propiedad hasMembersWithLicenseErrors es una excepción y no se devuelve en la consulta $select.The hasMembersWithLicenseErrors property is an exception and is not returned in the $select query.

PermisosPermissions

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Tipo de permisoPermission type Permisos (de menos a más privilegiados)Permissions (from least to most privileged)
Delegado (cuenta profesional o educativa)Delegated (work or school account) GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.AllGroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegado (cuenta personal de Microsoft)Delegated (personal Microsoft account) No admitida.Not supported.
AplicaciónApplication GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.AllGroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All

Solicitud HTTPHTTP request

GET /groups

Parámetros de consulta opcionalesOptional query parameters

Para enumerar únicamente grupos de Microsoft 365 (también denominados grupos unificados), aplique un filtro en groupTypes:To list only Microsoft 365 groups (aka unified groups), apply a filter on groupTypes:

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

Puede usar la opción de consulta de OData $orderby para ordenar grupos de una organización por el valor displayName, tal y como se muestra en el ejemplo siguiente:You can use the OData query option $orderby to sort groups in an organization by the displayName values, as shown in the following example:

GET https://graph.microsoft.com/beta/groups?$orderby=displayName

También puede usar los parámetros de consulta $count y $search para limitar la respuesta.You can also use the $count and $search query parameters to limit the response. El parámetro de consulta $search solo admite la tokenización en los campos displayName y description.The $search query parameter supports tokenization only on the displayName and description fields. Otros campos tienen por defecto el comportamiento $filter.Other fields default to $filter behavior. Cuando se agregan o actualizan elementos para este recurso, se indexan específicamente para usarse con los parámetros de consulta $count y $search.When items are added or updated for this resource, they are specially indexed for use with the $count and $search query parameters. Puede producirse un leve retraso entre el momento en que se agrega o se actualiza un elemento y el momento en que está disponible en el índice.There can be a slight delay between when an item is added or updated and when it is available in the index.

Para más información, vea Parámetros de consulta OData.For more information, see OData query parameters.

Encabezados de solicitudRequest headers

NombreName DescripciónDescription
AuthorizationAuthorization {token} de portador. Obligatorio.Bearer {token}. Required.
ConsistencyLevelConsistencyLevel eventual.eventual. Este encabezado y $count se necesitan al usar $search, o al usar $filter con el parámetro de consulta $orderby.This header and $count are required when using $search, or when using $filter with the $orderby query parameter. Usa un índice que es posible que no esté actualizado con los cambios recientes realizados en el objeto.It uses an index that may not be up-to-date with recent changes to the object.

Cuerpo de la solicitudRequest body

No proporcione un cuerpo de solicitud para este método.Do not supply a request body for this method.

RespuestaResponse

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.If successful, this method returns a 200 OK response code and collection of group objects in the response body. La respuesta incluye sólo las propiedades predeterminadas de cada grupo.The response includes only the default properties of each group.

EjemplosExamples

Ejemplo 1: Obtener una lista de gruposExample 1: Get a list of groups

SolicitudRequest

Aquí tiene un ejemplo de la solicitud.The following is an example of the request.

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

RespuestaResponse

Aquí tiene un ejemplo de la respuesta.The following is an example of the response.

Nota: Se puede reducir el objeto de respuesta que se muestra aquí para mejorar la legibilidad.Note: The response object shown here might be shortened for readability. Se devolverán las propiedades predeterminadas para cada grupo de una llamada real.All the default properties are returned for each group in an actual call.

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":[
         ]
      }
   ]
}

Ejemplo 2: Obtener una lista filtrada de grupos, incluido el recuento de los objetos devueltosExample 2: Get a filtered list of groups including the count of returned objects

SolicitudRequest

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

RespuestaResponse

El siguiente es un ejemplo de respuesta que incluye solo las propiedades solicitadas.The following is an example of the response which includes only the requested properties.

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

Ejemplo 3: Obtener solo un recuento de gruposExample 3: Get only a count of groups

SolicitudRequest

Aquí tiene un ejemplo de la solicitud.The following is an example of the request.

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

RespuestaResponse

Este es un ejemplo de la respuesta.The following is an example of the response.

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 devueltosExample 4: Use $filter and $top to get one group with a display name that starts with 'a' including a count of returned objects

SolicitudRequest

Aquí tiene un ejemplo de la solicitud.The following is an example of the request.

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

RespuestaResponse

Aquí tiene un ejemplo de la respuesta.The following is an example of the response.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad. Se devolverán todas las propiedades de una llamada real.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

Ejemplo 5: Usar $search para obtener grupos con nombres para mostrar que contienen las letras 'Video', incluido un recuento de los objetos devueltosExample 5: Use $search to get groups with display names that contain the letters 'Video' including a count of returned objects

SolicitudRequest

Aquí tiene un ejemplo de la solicitud.The following is an example of the request.

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

RespuestaResponse

Aquí tiene un ejemplo de la respuesta.The following is an example of the response.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad. Se devolverán todas las propiedades de una llamada real.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

Ejemplo 6: Usar $search para obtener grupos con nombres para mostrar que contienen las letras 'Video' o una descripción que contiene las letras 'prod' , incluido un recuento de los objetos devueltosExample 6: Use $search to get groups with display names that contain the letters 'Video' or a description that contains the letters 'prod' including a count of returned objects

SolicitudRequest

Aquí tiene un ejemplo de la solicitud.The following is an example of the request.

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

RespuestaResponse

Aquí tiene un ejemplo de la respuesta.The following is an example of the response.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad. Se devolverán todas las propiedades de una llamada real.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

Ejemplo 7: mostrar los grupos dinámicos, filtrados por la opción membershipRuleProcessingState habilitadaExample 7: List dynamic groups, filtered by enabled membershipRuleProcessingState

SolicitudRequest

Aquí tiene un ejemplo de la solicitud.The following is an example of the request.

GET https://graph.microsoft.com/beta/groups?$select=id,membershipRule,membershipRuleProcessingState,membershipRuleProcessingStatus&$filter=membershipRuleProcessingState eq 'On'

RespuestaResponse

Este es un ejemplo de la respuesta.The following is an example of the response.

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

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups(id,membershipRule,membershipRuleProcessingState,membershipRuleProcessingStatus)",
   "value":[
      {
         "id":"1cdf9c18-a7dc-46b1-b47f-094d5656376d",
         "membershipRule":"user.accountEnabled -eq false",
         "membershipRuleProcessingState":"On",
         "membershipRuleProcessingStatus":{
            "status":"Succeeded",
            "lastMembershipUpdated":"2020-09-14T00:00:00Z",
            "errorMessage":null
         }
      }
   ]
}