Crear grupo

Espacio de nombres: microsoft.graph

Crear un nuevo grupo como se especifica en el cuerpo de la solicitud. Se pueden crear los siguientes tipos de grupos:

  • Grupo de Microsoft 365 (grupo unificado)
  • Grupo de seguridad

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 y especifique las propiedades de una opción de consulta de OData $select.

Nota: Aunque Microsoft Teams está compilado en grupos de Microsoft 365, actualmente no puede crear ningún equipo a través de esta API. Puede usar las otras API de grupo para administrar un equipo que se ha creado en la interfaz de usuario de Microsoft Teams.

Permisos

Se requiere uno de los permisos siguientes para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) Group.ReadWrite.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación Group.Create, Group.ReadWrite.All, Directory.ReadWrite.All

Para que una aplicación cree un grupo con propietarios o miembros mientras tenga el permiso Group.Create , la aplicación debe tener los privilegios para leer el tipo de objeto que quiere asignar como propietario o miembro del grupo. Por lo tanto:

  • La aplicación puede asignarse a sí misma como propietario o miembro del grupo.
  • Para crear el grupo con usuarios como propietarios o miembros, la aplicación debe tener al menos el permiso User.Read.All .
  • Para crear el grupo con otras entidades de servicio como propietarios o miembros, la aplicación debe tener al menos el permiso Application.Read.All .
  • Para crear el grupo con usuarios o entidades de servicio como propietarios o miembros, la aplicación debe tener al menos el permiso Directory.Read.All .

Solicitud HTTP

POST /groups

Encabezados de solicitud

Nombre Descripción
Authorization Portador {token}. Obligatorio.
Content-Type application/json

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON del objeto de grupo.

En la tabla siguiente se muestran las propiedades necesarias para crear el grupo. Especifique otras propiedades modificables según sea necesario para su grupo.

Propiedad Tipo Descripción
displayName Cadena El nombre para mostrar en la lista de direcciones del grupo. Longitud máxima: 256 caracteres. Obligatorio.
mailEnabled Booleano Se establece en true para grupos habilitados para correo electrónico. Obligatorio.
mailNickname Cadena El alias de correo para el grupo, único para los grupos de Microsoft 365 en la organización. La longitud máxima es de 64 caracteres. Esta propiedad solo puede contener caracteres incluidos en el juego de caracteres ASCII de 0 a 127 con estas excepciones: @ () \ [] " ; : <> , SPACE. Obligatorio.
securityEnabled Booleano Se establece en true para grupos habilitados para seguridad, incluidos grupos de Microsoft 365. Obligatorio. Nota: los grupos creados con Microsoft Azure Portal siempre tienen securityEnabled inicialmente establecido como true.

Importante

  • Crear un grupo con elGrupo. Crear un permiso de la aplicación sin especificar propietarios creará el grupo de forma anónima y el grupo no podrá ser modificable. Agregue propietarios al grupo mientras lo crea para especificar propietarios que pueden modificar el grupo.

  • Crear un grupo de Microsoft 365 mediante programación con un contexto de solo app y sin especificar los propietarios creará el grupo de forma anónima. Si lo hace, el sitio de SharePoint Online asociado puede que no se cree automáticamente hasta que no se realicen acciones manuales adicionales.

  • Las siguientes propiedades no se pueden establecer en la solicitud POST inicial y deben establecerse en una solicitud PATCH posterior: allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribedByMail, unseenCount.

Opciones de groupTypes

Use la propiedad groupTypes para controlar el tipo de grupo y sus miembros, como se le muestra.

Tipo de grupo Pertenencia asignada Pertenencia dinámica
Microsoft 365 (también conocido como grupo unificado) ["Unified"] ["Unified","DynamicMembership"]
Dinámico [](null) ["DynamicMembership"]

Respuesta

Si se ejecuta correctamente, este método devuelve un código de respuesta 201 Created y un objeto group en el cuerpo de la respuesta. La respuesta incluye solo las propiedades predeterminadas del grupo.

Ejemplos

Ejemplo 1: crear un grupo de Microsoft 365

El ejemplo siguiente crea un grupo de Microsoft 365. Dado que no se han especificado los propietarios, el usuario que llama se agrega automáticamente como propietario del grupo.

Solicitud

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
  "description": "Self help community for library",
  "displayName": "Library Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "library",
  "securityEnabled": false
}

Respuesta

Aquí tiene un ejemplo de la respuesta. El valor de la propiedad preferredDataLocation se hereda de la ubicación de datos preferida del creador del grupo.

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

{
    "id": "b320ee12-b1cd-4cca-b648-a437be61c5cd",
	  "deletedDateTime": null,
	  "classification": null,
	  "createdDateTime": "2018-12-22T00:51:37Z",
	  "description": "Self help community for library",
	  "displayName": "Library Assist",
	  "groupTypes": [
	      "Unified"
	  ],
	  "mail": "library7423@contoso.com",
	  "mailEnabled": true,
	  "mailNickname": "library",
	  "onPremisesLastSyncDateTime": null,
	  "onPremisesSecurityIdentifier": null,
	  "onPremisesSyncEnabled": null,
	  "preferredDataLocation": "CAN",
	  "proxyAddresses": [
	      "SMTP:library7423@contoso.com"
	  ],
	  "renewedDateTime": "2018-12-22T00:51:37Z",
	  "resourceBehaviorOptions": [],
	  "resourceProvisioningOptions": [],
	  "securityEnabled": false,
	  "visibility": "Public",
	  "onPremisesProvisioningErrors": []
}

Ejemplo 2: crear un grupo con miembros y propietarios

El ejemplo siguiente crea un grupo de seguridad con un propietario y los miembros especificados. Es necesario tener en cuenta que se puede agregar un máximo de 20 relaciones, como propietarios y miembros, como parte de la creación del grupo. Seguidamente, puede agregar más miembros utilizando la API de miembros o procesamiento por lotes JSON.

Solicitud

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
  ],
  "mailEnabled": false,
  "mailNickname": "operations2019",
  "securityEnabled": true,
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

Respuesta

Aquí se muestra el ejemplo de una respuesta correcta. Incluye solo propiedades predeterminadas. Luego, puede obtener las propiedades de navegación propietarios o miembros del grupo para comprobar los detalles del propietario y los miembros. El valor de la propiedad preferredDataLocation se hereda de la ubicación de datos preferida del creador del grupo.

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

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/21d05557-b7b6-418f-86fa-a3118d751be4/Microsoft.DirectoryServices.Group",
    "id": "21d05557-b7b6-418f-86fa-a3118d751be4",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:09:14Z",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "isAssignableToRole": null,
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "operations2019",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": null,
    "preferredLanguage": null,
    "proxyAddresses": [],
    "renewedDateTime": "2021-09-21T07:09:14Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-567301463-1099937718-295959174-3827004813",
    "theme": null,
    "visibility": null,
    "onPremisesProvisioningErrors": []
}

Ejemplo 3: Crear un grupo de Microsoft 365 que se pueda asignar a un rol de Azure AD

Solicitud

Aquí tiene un ejemplo de la solicitud. Al usuario que realiza la llamada se le debe asignar el permiso RoleManagement.ReadWrite.Directory para establecer la propiedad isAssignableToRole o actualizar la pertenencia de dichos grupos.

Un grupo con la propiedad isAssignableToRole establecida true en no puede ser de tipo de pertenencia dinámica, su valor securityEnabled debe establecerse en truey la visibilidad solo puede ser Private.

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": true,
    "mailEnabled": true,
    "securityEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

Nota: Un grupo con propiedad isAssignableToRole establecida en true no puede ser de tipo de pertenencia dinámica y no puede tener un propietario. Para más información, consulte Usar un grupo para administrar las asignaciones de roles de Azure AD.

Respuesta

Aquí tiene un ejemplo de la respuesta. Incluye solo propiedades predeterminadas. El valor de la propiedadpreferredDataLocation se hereda de la ubicación de datos preferida del creador del grupo.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/55ea2e8c-757f-4f2d-be9e-53c22e8c6a54/Microsoft.DirectoryServices.Group",
    "id": "55ea2e8c-757f-4f2d-be9e-53c22e8c6a54",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:23:06Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "infoCatalogs": [],
    "isAssignableToRole": true,
    "isManagementRestricted": null,
    "mail": "contosohelpdeskadministrators@M365x010717.onmicrosoft.com",
    "mailEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "EU",
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:contosohelpdeskadministrators@M365x010717.onmicrosoft.com"
    ],
    "renewedDateTime": "2021-09-21T07:23:06Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-1441410700-1328379263-3260260030-1416268846",
    "theme": null,
    "visibility": "Private",
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}