Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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.
Utilice esta API para agregar un miembro (usuario, grupo o dispositivo) a una unidad administrativa o para crear un nuevo grupo dentro de una unidad administrativa. Todos los tipos de grupo se pueden crear dentro de una unidad administrativa.
Nota: Actualmente, solo es posible agregar un miembro a la vez a una unidad administrativa".
Esta API está disponible en las siguientes implementaciones en la nube nacional.
| Servicio global | Administración pública de EE. UU. | Gobierno de EE. UU. L5 (DOD) | China operado por 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Permisos
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.
Permisos para agregar un usuario, grupo o dispositivo existente
| Tipo de permiso | Permisos (de menos a más privilegiados) |
|---|---|
| Delegado (cuenta profesional o educativa) | AdministrativeUnit.ReadWrite.All |
| Delegado (cuenta personal de Microsoft) | No admitida. |
| Aplicación | AdministrativeUnit.ReadWrite.All |
Importante
Para el acceso delegado con cuentas profesionales o educativas, el usuario que ha iniciado sesión debe ser un usuario miembro o tener asignado un rol compatible de Microsoft Entra o un rol personalizado que conceda los permisos necesarios para esta operación. sEl administrador de roles con privilegios es el rol con privilegios mínimos admitido para esta operación.
Permisos para crear un nuevo grupo
| Tipo de permiso | Permisos (de menos a más privilegiados) |
|---|---|
| Delegado (cuenta profesional o educativa) | Group.ReadWrite.All y AdministrativeUnit.Read.All, Directory.ReadWrite.All |
| Delegado (cuenta personal de Microsoft) | No admitida. |
| Aplicación | Group.Create y AdministrativeUnit.Read.All, Group.ReadWrite.All y AdministrativeUnit.Read.All, Directory.ReadWrite.All |
Importante
Para crear un nuevo grupo en una unidad administrativa, la entidad de seguridad que llama debe tener asignada al menos una de las siguientes funciones de Microsoft Entra en el ámbito de la unidad administrativa:
- Administrador de grupos
- Administrador de usuarios
Para escenarios de solo aplicación, además de estos roles, la entidad de servicio requiere permisos adicionales para leer el directorio. Estos permisos se pueden conceder mediante la asignación de roles compatibles de Microsoft Entra, como el rol Lectores de directorio; o bien se pueden conceder mediante permisos de aplicación de Microsoft Graph que permiten leer el directorio, como Directory.Read.All.
Solicitud HTTP
La siguiente solicitud agrega un usuario, grupo o dispositivo existente a la unidad administrativa.
POST /administrativeUnits/{id}/members/$ref
La siguiente solicitud crea un nuevo grupo dentro de la unidad administrativa.
POST /administrativeUnits/{id}/members
Encabezados de solicitud
| Nombre | Descripción |
|---|---|
| Authorization | {token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización. |
| Tipo de contenido | application/json. Obligatorio. |
Agregar un usuario o grupo existente
En el cuerpo de la solicitud, proporcione el identificador de un usuario, grupo, dispositivo o directoryObject que se va a agregar. Si la unidad administrativa es una unidad administrativa de administración restringida ("isMemberManagementRestricted": true), el tipo de grupo debe ser un grupo de seguridad de Microsoft Entra. Solo se admiten los grupos no unificados que tienen habilitada la seguridad, no el correo y la sincronización local.
Crear un nuevo grupo
En la tabla siguiente se muestran las propiedades del recurso de grupo que se deben especificar al crear un grupo en la unidad administrativa.
| Propiedad | Tipo | Descripción |
|---|---|---|
| displayName | string | El nombre para mostrar en la lista de direcciones del grupo. Obligatorio. |
| description | cadena | Una descripción para el grupo. Opcional. |
| isAssignableToRole | Booleano | Establézcalo en verdadero para permitir que el grupo se asigne a un rol de Microsoft Entra. El administrador de roles con privilegios es el rol con privilegios mínimos para establecer el valor de esta propiedad. Opcional. |
| mailEnabled | Booleano | Establézcalo a true para grupos habilitados para correo electrónico. Obligatorio. |
| mailNickname | string | El alias de correo del grupo. Estos caracteres no se pueden usar en la publicación mailNickName: @()\[]";:.<>,SPACE. Obligatorio. |
| securityEnabled | Booleano | Establecer en true para grupos con seguridad habilitada, incluyendo los grupos de Microsoft 365. Necesario. |
| owners | Colección directoryObject | Esta propiedad representa los propietarios del grupo a la hora de creación. Opcional. |
| members | Colección directoryObject | Esta propiedad representa los miembros del grupo a la hora de creación. Opcional. |
| visibility | Cadena | Especifica la visibilidad de un grupo de Microsoft 365. Los valores posibles son: Private, Public, HiddenMembershipo vacío (que se interpreta como Public). |
Respuesta
Si se realiza correctamente, la adición de un objeto existente (mediante $ref) devuelve el 204 No Content código de respuesta. No devuelve nada en el cuerpo de la respuesta.
Al crear un nuevo grupo (sin $ref), este método devuelve un 201 Created código de respuesta y un objeto de grupo en el cuerpo de la respuesta. La respuesta incluye solo las propiedades predeterminadas del grupo. Debe proporcionar la "@odata.type" : "#microsoft.graph.group" línea en el cuerpo de la solicitud para identificar explícitamente al nuevo miembro como grupo. Un cuerpo de solicitud sin el correcto @odata.type devuelve un mensaje de 400 Bad Request error.
Ejemplos
Ejemplo 1: Agregar un usuario o grupo existente
Lo siguiente agregará un usuario o grupo existente a la unidad administrativa.
Solicitud
En el ejemplo siguiente se muestra la solicitud.
POST https://graph.microsoft.com/beta/administrativeUnits/{id}/members/$ref
Content-type: application/json
{
"@odata.id":"https://graph.microsoft.com/beta/groups/{id}"
}
En el cuerpo de la solicitud, proporcione id el objeto de usuario, grupo o dispositivo que desea agregar.
Respuesta
En el ejemplo siguiente se muestra la respuesta.
HTTP/1.1 204 No Content
Ejemplo 2: Crear un grupo nuevo
El siguiente ejemplo crea un nuevo grupo en la unidad administrativa. Debe proporcionar la "@odata.type" : "#microsoft.graph.group" línea en el cuerpo de la solicitud para identificar explícitamente al nuevo miembro como grupo. Un cuerpo de solicitud sin el correcto @odata.type devuelve un mensaje de 400 Bad Request error.
Solicitud
En el ejemplo siguiente se muestra la solicitud.
POST https://graph.microsoft.com/beta/administrativeUnits/{id}/members
Content-type: application/json
{
"@odata.type": "#microsoft.graph.group",
"description": "Self help community for golf",
"displayName": "Golf Assist",
"groupTypes": [
"Unified"
],
"mailEnabled": true,
"mailNickname": "golfassist",
"securityEnabled": false
}
En el cuerpo de la solicitud, proporcione las propiedades del objeto de grupo que desea agregar.
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 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
"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"
],
"renewedDateTime": "2018-12-22T02:21:05Z",
"resourceBehaviorOptions": [],
"resourceProvisioningOptions": [],
"securityEnabled": false,
"securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
"theme": null,
"visibility": "Public",
"onPremisesProvisioningErrors": []
}