Agregar miembros
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.
Agregue un miembro a un grupo de seguridad o de Microsoft 365. Al usar la API para agregar varios miembros en una solicitud, solo puede agregar hasta 20 miembros.
En la tabla siguiente se muestran los tipos de miembros que se pueden agregar a grupos de seguridad o grupos de Microsoft 365.
Tipo de objeto | Miembro de grupo de seguridad | Miembro del grupo Microsoft 365 |
---|---|---|
User |
|
|
Grupo de seguridad |
|
|
Grupo de Microsoft 365 |
|
|
Dispositivo |
|
|
Servicio principal |
|
|
Contacto organizacional |
|
|
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
En la tabla siguiente se muestra el permiso con privilegios mínimos que requiere cada tipo de recurso al llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.
Recurso admitido | Delegado (cuenta profesional o educativa) | Delegado (cuenta de Microsoft personal) | Aplicación |
---|---|---|---|
dispositivo | GroupMember.ReadWrite.All y Device.ReadWrite.All | No admitida. | GroupMember.ReadWrite.All y Device.ReadWrite.All |
group | GroupMember.ReadWrite.All | No admitida. | GroupMember.ReadWrite.All |
orgContact | GroupMember.ReadWrite.All y OrgContact.Read.All | No admitida. | GroupMember.ReadWrite.All y OrgContact.Read.All |
servicePrincipal | GroupMember.ReadWrite.All y Application.ReadWrite.All | No admitida. | GroupMember.ReadWrite.All y Application.ReadWrite.All |
user | GroupMember.ReadWrite.All | No admitida. | GroupMember.ReadWrite.All |
Importante
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 permiso de microsoft.directory/groups/members/update
rol. Los siguientes roles son los roles con privilegios mínimos que se admiten para esta operación, excepto para los grupos asignables por roles:
- Propietarios de grupos
- Escritores de directorios
- Administrador de grupos
- Administrador de gobernanza de identidades
- Administrador de usuarios
- Administrador de Exchange: solo para grupos de Microsoft 365
- Administrador de SharePoint: solo para grupos de Microsoft 365
- Administrador de Teams: solo para grupos de Microsoft 365
- Administrador de Yammer: solo para grupos de Microsoft 365
- administrador de Intune: solo para grupos de seguridad
Para agregar miembros a un grupo asignable a roles, a la aplicación también se le debe asignar el permiso RoleManagement.ReadWrite.Directory y al usuario que realiza la llamada se le debe asignar un rol de Microsoft Entra compatible. Privileged Role Administrator es el rol con privilegios mínimos que se admite para esta operación.
Solicitud HTTP
POST /groups/{group-id}/members/$ref
PATCH /groups/{group-id}/members
Encabezados de solicitud
Nombre | Descripción |
---|---|
Authorization | {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización. |
Tipo de contenido | application/json. Obligatorio. |
Cuerpo de la solicitud
Al usar la POST /groups/{group-id}/members/$ref
sintaxis, proporcione un objeto JSON que contenga una propiedad @odata.id con una referencia por identificador a un tipo de objeto miembro de grupo compatible.
Al usar la PATCH /groups/{group-id}/members
sintaxis, proporcione un objeto JSON que contenga una members@odata.bind propiedad con una o varias referencias por identificadores a un tipo de objeto miembro de grupo compatible. Es decir:
- En el caso de los grupos de Microsoft 365, solo
https://graph.microsoft.com/v1.0/directoryObjects/{id}
se permite yhttps://graph.microsoft.com/v1.0/groups/{id}
donde{id}
debe ser un usuario, ya que solo los usuarios pueden pertenecer a grupos de Microsoft 365. - En el caso de los grupos de seguridad, se permiten las siguientes referencias de identificador:
-
https://graph.microsoft.com/v1.0/directoryObjects/{id}
donde{id}
debe pertenecer a un usuario, grupo de seguridad, dispositivo, entidad de servicio o contacto organizativo. -
https://graph.microsoft.com/v1.0/groups/{id}
donde{id}
debe pertenecer a otro grupo de seguridad. Los grupos de Microsoft 365 no pueden ser miembros de grupos de seguridad. -
https://graph.microsoft.com/v1.0/devices/{id}
donde{id}
pertenece a un dispositivo. -
https://graph.microsoft.com/v1.0/servicePrincipal/{id}
donde{id}
pertenece a una entidad de servicio. -
https://graph.microsoft.com/v1.0/orgContact/{id}
donde{id}
pertenece a un contacto de la organización.
-
Respuesta
Si se ejecuta correctamente, este método devuelve un código de respuesta 204 No Content
. Devuelve un código de 400 Bad Request
respuesta cuando el objeto ya es miembro del grupo o no es compatible como miembro del grupo. Devuelve un código de 404 Not Found
respuesta cuando el objeto que se agrega no existe.
403 Unauthorized
Devuelve en uno de los siguientes escenarios:
- Está intentando agregar un miembro a un grupo que no se puede administrar a través de Microsoft Graph. Esta API solo admite grupos de seguridad y microsoft 365.
- Está intentando agregar un miembro que no tiene permisos para agregar. Consulte la sección Permisos anterior para obtener los permisos necesarios para agregar diferentes tipos de miembros.
- Está intentando agregar un miembro a un grupo asignable a roles y no tiene los permisos necesarios.
Ejemplo
Ejemplo 1: Agregar un miembro a un grupo
Solicitud
En el ejemplo siguiente se muestra una solicitud que usa la referencia directoryObjects para agregar un miembro a un grupo.
POST https://graph.microsoft.com/beta/groups/{group-id}/members/$ref
Content-type: application/json
{
"@odata.id": "https://graph.microsoft.com/beta/directoryObjects/{id}"
}
Respuesta
En el ejemplo siguiente se muestra la respuesta.
HTTP/1.1 204 No Content
Ejemplo 2: agregar varios miembros a un grupo en una sola solicitud
Este ejemplo muestra cómo agregar varios miembros a un grupo compatible con BIND de OData en una operación PATCH. Se pueden agregar hasta 20 miembros en una sola solicitud. Si existe una condición de error en el cuerpo de la solicitud, no se agregarán miembros y se devolverá el código de respuesta apropiado.
Solicitud
En el ejemplo siguiente se muestra la solicitud.
PATCH https://graph.microsoft.com/beta/groups/{group-id}
Content-type: application/json
{
"members@odata.bind": [
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}"
]
}
Respuesta
En el ejemplo siguiente se muestra la respuesta.
HTTP/1.1 204 No Content