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.
Microsoft Graph API permite que las aplicaciones administren comunidades y roles en Viva Engage. Viva Engage es un tejido social para la Microsoft Viva suite de aplicaciones que conecta a personas de toda la organización para compartir y aprender. Es un lugar donde los empleados pueden conectarse con líderes, compañeros de trabajo y comunidades, compartir sus conocimientos e ideas y encontrar pertenencia en el trabajo.
Importante
La API de Viva Engage de Microsoft Graph solo se admite para redes Viva Engage en modo nativo. No puede usar esta API para administrar redes Viva Engage heredadas o externas.
Autorización
Para llamar a la API de Viva Engage en Microsoft Graph, la aplicación debe adquirir un token de acceso. Para obtener más información sobre los tokens de acceso, vea Obtener tokens de acceso para llamar a Microsoft Graph. La aplicación también necesita los permisos adecuados. Para más información, vea Permisos de Microsoft Graph.
Casos de uso comunes
En la tabla siguiente se enumeran los casos de uso comunes de la API de Viva Engage.
| Caso de uso | API | Notas |
|---|---|---|
| Creación de una comunidad | POST /employeeExperience/communities | Si se ejecuta correctamente, este método devuelve un 202 Accepted código de respuesta que contiene un vínculo a un objeto engagementAsyncOperation . |
| Sondeo del estado de creación de la comunidad | GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId} | Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y un objeto engagementAsyncOperation en el cuerpo de la respuesta. Compruebe periódicamente el estado de la operación realizando una solicitud GET a esta ubicación; espere >30 segundos entre las comprobaciones. Cuando la solicitud se completa correctamente, el estado indica succeeded y resourceLocation apunta al recurso creado o modificado. |
| Obtener una comunidad después de la creación | GET /employeeExperience/communities/{communityId} | Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y un objeto de comunidad en el cuerpo de la respuesta. El objeto community hace referencia al identificador de grupo de Microsoft 365 asociado que puede usar para la administración de pertenencia a la comunidad y propiedad. |
| Obtener una lista de comunidades | GET /employeeExperience/communities | Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una colección de Viva Engage objetos de la comunidad en el cuerpo de la respuesta. |
| Actualización de una comunidad | PATCH /employeeExperience/communities/{communityId} | Si se ejecuta correctamente, este método actualiza una comunidad Viva Engage existente y devuelve un código de 204 No Content respuesta. |
| Eliminación de una comunidad | DELETE /employeeExperience/communities/{communityId} | Si se ejecuta correctamente, este método elimina una comunidad de Viva Engage junto con todo el contenido de Microsoft 365 asociado, incluido el grupo de Microsoft 365 conectado, el cuaderno de OneNote y los planes de Planner conectados. Para obtener más información, consulte ¿Qué ocurre si elimino una comunidad de Viva Engage conectada a grupos de Microsoft 365? |
| Agregar miembros a una comunidad | POST /groups/{groupId}/members/$ref | Cuando se agregan nuevos miembros a un grupo, la pertenencia asociada de la comunidad se actualiza automáticamente. |
| Eliminación de un miembro de una comunidad | DELETE /groups/{groupId}/members/{userId}/$ref | Cuando se quita un miembro de un grupo, la pertenencia asociada de la comunidad se actualiza automáticamente. |
| Agregar un administrador de la comunidad | POST /groups/{groupId}/owners/$ref | Cuando se agrega un usuario como propietario del grupo, se convierte automáticamente en administrador de la comunidad asociada. |
| Eliminación de un administrador de la comunidad | DELETE /groups/{groupId}/owners/{userId}/$ref | Cuando se quita un propietario de grupo, deja de ser administrador de la comunidad asociada. No se puede quitar el último propietario (objeto de usuario ) de un grupo. |
| Administración de roles | ||
| Obtener una lista estática de los tipos de rol admitidos en Viva Engage | GET /employeeExperience/roles | Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una lista de roles en el cuerpo de la respuesta. |
| Obtener una lista de usuarios con un rol de Viva Engage específico | GET /employeeExperience/roles/{engagementRoleId}/members | Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una lista de miembros del rol de interacción en el cuerpo de la respuesta. |
| Obtener una lista de roles de Viva Engage asignados al usuario que ha iniciado sesión | GET /me/employeeExperience/assignedRoles | Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una lista de roles en el cuerpo de la respuesta. |
| Obtener una lista de roles Viva Engage asignados a un usuario | GET /users/{userId}/employeeExperience/assignedRoles | Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una lista de roles en el cuerpo de la respuesta. |
| Asignación de un rol de Viva Engage a un usuario | POST /employeeExperience/roles/{engagementRoleId}/members | Si se ejecuta correctamente, este método asigna un rol de Viva Engage a un usuario. |
| Eliminación de un rol de Viva Engage de un usuario | DELETE /employeeExperience/roles/{roleId}/members/{userId} | Si se ejecuta correctamente, este método revoca un rol de Viva Engage de un usuario. |
Comunidades y grupos
Para Viva Engage redes en modo nativo, la creación de una nueva comunidad de Viva Engage también da como resultado la creación de un grupo de Microsoft 365 conectado, junto con un nuevo sitio de SharePoint, un cuaderno de OneNote y un plan de Planner. Use el grupo asociado para administrar las operaciones en una comunidad, por ejemplo:
- Agregar o quitar miembros del grupo
- Administración de la propiedad del grupo
- Eliminar un grupo
- Cambiar el nombre de un grupo
- Actualización de la descripción del grupo
Para obtener más información sobre la relación entre las comunidades Viva Engage y los grupos de Microsoft 365, consulte Viva Engage y Grupos de Microsoft 365.
Nota: No puede usar la API Crear grupo para aprovisionar una comunidad de Viva Engage.
Administración de roles
Viva Engage admite el acceso basado en roles al habilitar la asignación de roles administrativos predefinidos (como administrador de red y administrador verificado) y roles de comunicación corporativa dentro de la plataforma.
Estos roles asignables están predefinidos y administrados por Viva Engage. Los roles personalizados no se pueden crear ni eliminar. Para obtener más información, consulte Administración de roles de administrador en Viva Engage.
Microsoft Entra roles se administran a través del centro de administración de Microsoft Entra, mientras que los roles específicos de Viva Engage se pueden asignar y administrar mediante la plataforma de Viva Engage y las API de Microsoft Graph. Para obtener más información, consulte Centro de administración de Microsoft 365 guía.
Límites de API
Viva Engage llamadas API están sujetas a limitación de velocidad, lo que permite 10 solicitudes por usuario, por aplicación, en un período de tiempo de 30 segundos. Cuando se supera el límite de velocidad, todas las solicitudes posteriores devuelven un código de 429 Too Many Requests respuesta.
Para obtener instrucciones sobre cómo controlar la limitación en Microsoft Graph, consulte Guía de limitación de Microsoft Graph.
Pasos siguientes
- Use microsoft Graph API para administrar comunidades y roles en Viva Engage.
- Pruebe la API de Viva Engage en el Explorador de Graph.