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.
A API do Graph permite que os aplicativos gerenciem comunidades e funções no Viva Engage. O Viva Engage é uma malha social para o conjunto Microsoft Viva de aplicativos que conecta pessoas em toda a organização para compartilhar e aprender. É um lugar onde os funcionários podem se conectar com líderes, colegas de trabalho e comunidades, compartilhar seus conhecimentos e ideias e encontrar pertencimento no trabalho.
Importante
A API do Viva Engage no Microsoft Graph só tem suporte para redes do Viva Engage no modo nativo. Você não pode usar essa API para gerenciar redes herdadas ou externas do Viva Engage.
Authorization
Para chamar a API do Viva Engage no Microsoft Graph, seu aplicativo precisa adquirir um token de acesso. Para obter detalhes sobre tokens de acesso, confira Obter tokens de acesso para chamar o Microsoft Graph. Seu aplicativo também precisa das permissões apropriadas. Para saber mais, confira Referência de permissões do Microsoft Graph.
Casos de uso comuns
A tabela a seguir lista casos de uso comuns para a API do Viva Engage.
| Caso de uso | API | Observações |
|---|---|---|
| Criar uma comunidade | POST /employeeExperience/communities | Se for bem-sucedido, esse método retornará um código de 202 Accepted resposta que contém um link para um objeto engagementAsyncOperation . |
| Votação para o status de criação da comunidade | GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId} | Se for bem-sucedido, esse método retornará um código de 200 OK resposta e um objeto engagementAsyncOperation no corpo da resposta. Marque periodicamente o status da operação fazendo uma solicitação GET para esse local; aguarde >30 segundos entre as verificações. Quando a solicitação é concluída 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, esse método retornará um código de 200 OK resposta e um objeto da comunidade no corpo da resposta. O objeto da comunidade faz referência à ID de grupo do Microsoft 365 associada que você pode usar para gerenciamento de associação e propriedade da comunidade. |
| Obter uma lista de comunidades | GET /employeeExperience/communities | Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma coleção de objetos da comunidade do Viva Engage no corpo da resposta. |
| Atualizar uma comunidade | PATCH /employeeExperience/communities/{communityId} | Se for bem-sucedido, esse método atualizará uma comunidade existente do Viva Engage e retornará um código de 204 No Content resposta. |
| Excluir uma comunidade | DELETE /employeeExperience/communities/{communityId} | Se for bem-sucedido, esse método excluirá uma comunidade do Viva Engage juntamente com todo o conteúdo associado do Microsoft 365, incluindo o grupo conectado do Microsoft 365, o bloco de anotações do OneNote e os planos do Planner. Para obter mais informações, consulte O que acontece se eu excluir uma comunidade do Viva Engage conectada a grupos do Microsoft 365. |
| Adicionar membros a uma comunidade | POST /groups/{groupId}/members/$ref | Quando novos membros são adicionados a um grupo, a associação associada da comunidade é atualizada automaticamente. |
| Remover um membro de uma comunidade | EXCLUIR /groups/{groupId}/members/{userId}/$ref | Quando um membro é removido de um grupo, a associação associada da comunidade é atualizada automaticamente. |
| Adicionar um administrador da comunidade | POST /groups/{groupId}/owners/$ref | Quando um usuário é adicionado como proprietário do grupo, ele se torna automaticamente um administrador da comunidade associada. |
| Remover um administrador da comunidade | DELETE /groups/{groupId}/owners/{userId}/$ref | Quando um proprietário de grupo é removido, ele deixa de ser administrador da comunidade associada. Não é possível remover o último proprietário (objeto de usuário ) de um grupo. |
| Gerenciamento de funções | ||
| Obtenha uma lista estática de tipos de função com suporte no Viva Engage | GET /employeeExperience/roles | Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma lista de funções no corpo da resposta. |
| Obtenha uma lista de usuários com uma função específica do Viva Engage | GET /employeeExperience/roles/{engagementRoleId}/members | Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma lista de membros da função de compromisso no corpo da resposta. |
| Obtenha uma lista de funções do Viva Engage atribuídas ao usuário conectado | GET /me/employeeExperience/assignedRoles | Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma lista de funções no corpo da resposta. |
| Obtenha uma lista de funções do Viva Engage atribuídas a um usuário | GET /users/{userId}/employeeExperience/assignedRoles | Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma lista de funções no corpo da resposta. |
| Atribuir uma função do Viva Engage a um usuário | POST /employeeExperience/roles/{engagementRoleId}/members | Se for bem-sucedido, esse método atribuirá uma função do Viva Engage a um usuário. |
| Excluir uma função do Viva Engage de um usuário | DELETE /employeeExperience/roles/{roleId}/members/{userId} | Se for bem-sucedido, esse método revogará uma função do Viva Engage de um usuário. |
Comunidades e grupos
Para redes do Viva Engage no modo nativo, a criação de uma nova comunidade do Viva Engage também resulta na criação de um grupo conectado do Microsoft 365, juntamente com um novo site do SharePoint, bloco de anotações do OneNote e plano do Planner. Use o grupo associado para gerenciar operações em uma comunidade, por exemplo:
- Adicionar ou remover membros do grupo
- Gerenciar a propriedade do grupo
- Excluir um grupo
- Renomear um grupo
- Atualize a descrição do grupo
Para obter mais informações sobre a relação entre as comunidades do Viva Engage e os grupos do Microsoft 365, consulte Grupos do Viva Engage e Grupos do Microsoft 365.
Observação: Você não pode usar a API Criar grupo para provisionar uma comunidade do Viva Engage.
Gerenciamento de funções
O Viva Engage dá suporte ao acesso baseado em função, permitindo a atribuição de funções administrativas predefinidas (como Administrador de Rede e Administrador Verificado) e funções de comunicação corporativa na plataforma.
Essas funções atribuíveis são predefinidas e gerenciadas pelo Viva Engage. As funções personalizadas não podem ser criadas nem excluídas. Para obter mais informações, consulte Gerenciar funções de administrador no Viva Engage.
As funções do Microsoft Entra são gerenciadas por meio do centro de administração do Microsoft Entra, enquanto as funções específicas do Viva Engage podem ser atribuídas e gerenciadas usando a plataforma Viva Engage e as APIs do Microsoft Graph. Para obter mais informações, confira o guia do Centro de administração do Microsoft 365.
Limites da API
As chamadas à API do Viva Engage estão sujeitas à limitação de taxa, permitindo 10 solicitações por usuário, por aplicativo, em um período de 30 segundos. Quando você excede o limite de taxa, todas as solicitações subsequentes retornam um código de 429 Too Many Requests resposta.
Para obter orientação sobre como lidar com a limitação no Microsoft Graph, consulte Orientação de limitação do Microsoft Graph.
Próximas etapas
- Use a API do Graph para gerenciar comunidades e funções no Viva Engage.
- Experimente a API do Viva Engage no Graph Explorer.