Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
O Microsoft API do Graph permite que as aplicações façam a gestão de comunidades e funções no Viva Engage. Viva Engage é um recurso de infraestrutura social para a conjunto Microsoft Viva de aplicações que liga pessoas em toda a organização para partilhar e aprender. É um local onde os funcionários se podem ligar a líderes, colegas e comunidades, partilhar os seus conhecimentos e ideias e encontrar pertença ao trabalho.
Importante
A API de Viva Engage no Microsoft Graph só é suportada para redes Viva Engage no modo nativo. Não pode utilizar esta API para gerir redes de Viva Engage legadas ou externas.
Authorization
Para chamar a API de Viva Engage no Microsoft Graph, a sua aplicação tem de adquirir um token de acesso. Para obter detalhes sobre tokens de acesso, confira Obter tokens de acesso para chamar o Microsoft Graph. A sua aplicação também precisa das permissões adequadas. Para saber mais, confira Referência de permissões do Microsoft Graph.
Casos de uso comuns
A tabela seguinte lista os casos de utilização comuns da API de Viva Engage.
| Caso de uso | API | Observações |
|---|---|---|
| Criar uma comunidade | POST /employeeExperience/communities | Se for bem-sucedido, este método devolve um 202 Accepted código de resposta que contém uma ligação para um objeto engagementAsyncOperation . |
| Inquérito sobre a criação da comunidade status | GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId} | Se for bem-sucedido, este método devolve um 200 OK código de resposta e um objeto engagementAsyncOperation no corpo da resposta. Periodicamente, marcar a status da operação ao fazer um pedido GET para esta localização; aguarde >30 segundos entre as verificações. Quando o pedido for concluído com êxito, o status indica succeeded e o resourceLocation aponta para o recurso criado ou modificado. |
| Obter uma comunidade após a criação | GET /employeeExperience/communities/{communityId} | Se for bem-sucedido, este método devolve um 200 OK código de resposta e um objeto de comunidade no corpo da resposta. O objeto de comunidade faz referência ao ID de grupo do Microsoft 365 associado que pode utilizar para a gestão de propriedade e associação à comunidade. |
| Obter uma lista de comunidades | GET /employeeExperience/communities | Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma coleção de objetos de comunidade Viva Engage no corpo da resposta. |
| Atualizar uma comunidade | PATCH /employeeExperience/communities/{communityId} | Se for bem-sucedido, este método atualiza uma comunidade Viva Engage existente e devolve um 204 No Content código de resposta. |
| Eliminar uma comunidade | DELETE /employeeExperience/communities/{communityId} | Se for bem-sucedido, este método elimina uma comunidade Viva Engage juntamente com todos os conteúdos do Microsoft 365 associados, incluindo o grupo ligado do Microsoft 365, o bloco de notas do OneNote e os planos de Planner. Para obter mais informações, consulte O que acontece se eliminar uma comunidade Viva Engage ligada a grupos do Microsoft 365. |
| Adicionar membros a uma comunidade | POST /groups/{groupId}/members/$ref | Quando são adicionados novos membros a um grupo, a associação associada à comunidade é atualizada automaticamente. |
| Remover um membro de uma comunidade | ELIMINAR /groups/{groupId}/members/{userId}/$ref | Quando um membro é removido de um grupo, a associação associada à comunidade é atualizada automaticamente. |
| Adicionar um administrador da comunidade | POST /groups/{groupId}/owners/$ref | Quando um utilizador é adicionado como proprietário de um grupo, torna-se automaticamente um administrador da comunidade associada. |
| Remover um administrador da comunidade | ELIMINAR /groups/{groupId}/owners/{userId}/$ref | Quando um proprietário do grupo é removido, deixa de ser administrador da comunidade associada. Não pode remover o último proprietário (objeto de utilizador ) de um grupo. |
| Gestão de funções | ||
| Obter uma lista estática de tipos de função suportados no Viva Engage | GET /employeeExperience/roles | Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma lista de funções no corpo da resposta. |
| Obter uma lista de utilizadores com uma função de Viva Engage específica | GET /employeeExperience/roles/{engagementRoleId}/members | Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma lista de membros da função de cativação no corpo da resposta. |
| Obter uma lista de Viva Engage funções atribuídas ao utilizador com sessão iniciada | GET /me/employeeExperience/assignedRoles | Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma lista de funções no corpo da resposta. |
| Obter uma lista de Viva Engage funções atribuídas a um utilizador | GET /users/{userId}/employeeExperience/assignedRoles | Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma lista de funções no corpo da resposta. |
| Atribuir uma função de Viva Engage a um utilizador | POST /employeeExperience/roles/{engagementRoleId}/members | Se for bem-sucedido, este método atribui uma função de Viva Engage a um utilizador. |
| Eliminar uma função de Viva Engage de um utilizador | DELETE /employeeExperience/roles/{roleId}/members/{userId} | Se for bem-sucedido, este método revoga uma função de Viva Engage de um utilizador. |
Comunidades e grupos
Para Viva Engage redes no modo nativo, a criação de uma nova comunidade Viva Engage também resulta na criação de um grupo ligado do Microsoft 365, juntamente com um novo site do SharePoint, bloco de notas do OneNote e plano de Planner. Utilize o grupo associado para gerir operações numa comunidade, por exemplo:
- Adicionar ou remover membros do grupo
- Gerir a propriedade do grupo
- Excluir um grupo
- Mudar o nome de um grupo
- Atualizar a descrição do grupo
Para obter mais informações sobre a relação entre comunidades Viva Engage e grupos do Microsoft 365, consulte Viva Engage e Grupos do Microsoft 365.
Nota: Não pode utilizar a API Criar grupo para aprovisionar uma comunidade Viva Engage.
Gestão de funções
Viva Engage suporta o acesso baseado em funções ao ativar a atribuição de funções administrativas predefinidas (como Administrador de Rede e Administrador Verificado) e funções de comunicação empresarial na plataforma.
Estas funções atribuíveis são predefinidas e geridas por Viva Engage. As funções personalizadas não podem ser criadas ou eliminadas. Para obter mais informações, veja Gerir funções de administrador no Viva Engage.
Microsoft Entra funções são geridas através do centro de administração do Microsoft Entra, enquanto Viva Engage funções específicas podem ser atribuídas e geridas com a plataforma Viva Engage e as APIs do Microsoft Graph. Para obter mais informações, consulte Centro de administração do Microsoft 365 guia.
Limites da API
Viva Engage chamadas à API estão sujeitas a limitação de taxa, permitindo 10 pedidos por utilizador, por aplicação, num período de tempo de 30 segundos. Quando excede o limite de taxa, todos os pedidos subsequentes devolvem um 429 Too Many Requests código de resposta.
Para obter orientações sobre como lidar com a limitação no Microsoft Graph, veja Orientações de limitação do Microsoft Graph.
Próximas etapas
- Utilize o microsoft API do Graph para gerir comunidades e funções no Viva Engage.
- Experimente a API de Viva Engage no Graph Explorer.