Compartir a través de

Ver miembros de grupo

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Obtiene una lista de los miembros directos del grupo. Un grupo puede tener usuarios, contactos, dispositivos, entidades de servicio y otros grupos como miembros. Esta operación no es transitiva.

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 Directory.Read.All, Group.Read.All, Group.ReadWrite.All, GroupMember.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación GroupMember.Read.All Directory.Read.All, Group.Read.All, Group.ReadWrite.All, GroupMember.ReadWrite.All

Importante

Cuando una aplicación consulta una relación que devuelve una colección de tipos directoryObject , si no tiene permiso para leer un tipo de recurso determinado, se devuelven miembros de ese tipo pero con información limitada. Por ejemplo, solo se devuelve la propiedad @odata.type para el tipo de objeto y el identificador , mientras que otras propiedades se indican como null. Con este comportamiento, las aplicaciones pueden solicitar los permisos con privilegios mínimos que necesitan, en lugar de depender del conjunto de directorios.*Permisos. Para información, consulte Información limitada devuelta para objetos de miembros inaccesibles.

En escenarios delegados, al usuario que ha iniciado sesión también se le debe asignar un rol de Microsoft Entra compatible o un rol personalizado con el microsoft.directory/groups/members/read permiso de rol o microsoft.directory/groups/members/limitedRead , o microsoft.directory/groups/hiddenMembers/read permiso de rol para leer miembros ocultos. Se admiten los siguientes roles con privilegios mínimos para esta operación:

  • Propietarios de grupos
  • Usuarios "miembros"
  • Usuarios "invitados": tienen permisos de lectura limitados
  • Lectores de directorio
  • Escritores de directorios
  • Administrador de grupos
  • Administrador de usuarios: incluidos los miembros ocultos
  • Administrador de Exchange: incluidos los miembros ocultos
  • Administrador de SharePoint: incluidos los miembros ocultos
  • Administrador de Intune: incluidos los miembros ocultos
  • Administrador de Teams: incluidos los miembros ocultos
  • Administrador de Yammer: incluidos los miembros ocultos

Para enumerar los miembros de un grupo de pertenencia oculto, también se requiere el permiso Member.Read.Hidden .

Solicitud HTTP

GET /groups/{id}/members

Parámetros de consulta opcionales

Este método admite los $filterparámetros de consulta , $count, $select, $search$top, $searchy $expand OData para ayudar a personalizar la respuesta. 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.

La conversión de OData también está habilitada. Por ejemplo, /groups/{id}}/members/microsoft.graph.user recupera los miembros del grupo que son usuarios.

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 requeridos al usar los parámetros de consulta $search, $filter, $orderby u OData. Usa un índice que podría no estar actualizado con los cambios recientes realizados en el objeto.

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 directoryObject en el cuerpo de la respuesta.

Un intento de filtrar por una conversión de OData que representa un tipo de miembro no admitido devuelve un 400 Bad Request error con el Request_UnsupportedQuery código. Por ejemplo, /groups/{id}}/members/microsoft.graph.group cuando el grupo es un grupo de Microsoft 365 devuelve este error, porque los grupos de Microsoft 365 no pueden tener otros grupos como miembros.

Ejemplos

Ejemplo 1: Obtenga la pertenencia directa a un grupo

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/groups/{id}/members

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

{
  "value": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "mail": "group1@contoso.com",
      "mailEnabled": true,
      "mailNickname": "Contoso1",
      "securityEnabled": true
    }
  ]
}

Ejemplo 2: Obtenga solo un recuento de todas las pertenencias

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/groups/{id}/members/$count
ConsistencyLevel: eventual

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

893

Ejemplo 3: Use la búsqueda de OData para obtener solo un recuento de pertenencias de usuarios.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/groups/{id}/members/microsoft.graph.user/$count
ConsistencyLevel: eventual

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

893

Ejemplo 4: Use $search y OData cast para obtener la pertenencia del usuario a grupos con nombres para mostrar que contengan las letras "Pr", incluido un recuento de objetos devueltos.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/groups/{id}/members/microsoft.graph.user?$count=true&$orderby=displayName&$search="displayName:Pr"&$select=displayName,id
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/beta/$metadata#users(displayName,id)",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Joseph Price",
      "id":"11111111-2222-3333-4444-555555555555"
    },
    {
      "displayName":"Preston Morales",
      "id":"11111111-2222-3333-4444-555555555555"
    }
  ]
}

Ejemplo 5: Use $filter para obtener las pertenencias a grupos con un nombre para mostrar que inicie con la letra “A”, incluido un recuento de los objetos devueltos.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/groups/{id}/members?$count=true&$filter=startswith(displayName, 'a')
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/beta/$metadata#groups",
  "@odata.count":76,
  "value":[
    {
      "displayName":"AAD Contoso Users",
      "mail":"AADContoso_Users@contoso.com",
      "mailEnabled":true,
      "mailNickname":"AADContoso_Users",
      "securityEnabled":true
    }
  ]
}

Ejemplo 6: Uso de la conversión de OData para recuperar las entidades de servicio agregadas como miembros del grupo

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/groups/3802e9bb-0951-4e18-b9eb-f934b4241194/members/microsoft.graph.servicePrincipal

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/beta/$metadata#servicePrincipals",
  "value": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "deletedDateTime": null,
      "accountEnabled": true,
      "appDisplayName": "Contoso Azure App",
      "appId": "11111111-2222-3333-4444-555555555555",
    }
  ]
}