Microsoft图形 API使应用能够管理Viva Engage中的社区和角色。 Viva Engage是一种社交结构，用于Microsoft Viva 套件应用，将组织中的人员联系起来，以便共享和学习。 在这里，员工可以与领导者、同事和社区联系，分享他们的知识和想法，并在工作中找到归属感。
重要
Microsoft Graph 中的Viva Engage API 仅支持本机模式下Viva Engage网络。 不能使用此 API 来管理旧版或外部Viva Engage网络。
Authorization
若要在 Microsoft Graph 中调用 Viva Engage API，应用需要获取访问令牌。 有关访问令牌的详细信息，请参阅获取用于调用 Microsoft Graph 的访问令牌。 你的应用还需要适当的权限。 有关详细信息，请参阅 Microsoft Graph 权限参考。
常见用例
下表列出了 Viva Engage API 的常见用例。
| 用例 | API | 注释 |
|---|---|---|
| 创建社区 | POST /employeeExperience/communities | 如果成功，此方法返回响应 202 Accepted 代码，其中包含 指向 engagementAsyncOperation 对象的链接。 |
| 社区创建状态的轮询 | GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId} | 如果成功，此方法在 200 OK 响应正文中返回响应代码和 engagementAsyncOperation 对象。 通过对此位置发出 GET 请求，定期检查作的状态;在检查之间等待 >30 秒。 请求成功完成时， 状态 指示 succeeded ， resourceLocation 指向已创建或修改的资源。 |
| 创建后获取社区 | GET /employeeExperience/communities/{communityId} | 如果成功，此方法在 200 OK 响应正文中返回响应代码 和社区 对象。 社区对象引用关联的 Microsoft 365 组 ID，可用于社区成员身份和所有权管理。 |
| 获取社区列表 | GET /employeeExperience/communities | 如果成功，此方法在响应正文中返回响应200 OK代码和Viva Engage社区对象的集合。 |
| 更新社区 | PATCH /employeeExperience/communities/{communityId} | 如果成功，此方法将更新现有Viva Engage社区并返回204 No Content响应代码。 |
| 删除社区 | DELETE /employeeExperience/communities/{communityId} | 如果成功，此方法将删除Viva Engage社区以及所有相关Microsoft 365 内容，包括连接的 Microsoft 365 组、OneNote 笔记本和Planner计划。 有关详细信息，请参阅删除连接到Microsoft 365 个组的Viva Engage社区会发生什么情况。 |
| 将成员添加到社区 | POST /groups/{groupId}/members/$ref | 将新成员添加到组后，社区的关联成员身份会自动更新。 |
| 从社区中删除成员 | DELETE /groups/{groupId}/members/{userId}/$ref | 从组中删除成员后，社区的关联成员身份会自动更新。 |
| 添加社区管理员 | POST /groups/{groupId}/owners/$ref | 将用户添加为组所有者后，他们会自动成为关联社区的管理员。 |
| 删除社区管理员 | DELETE /groups/{groupId}/owners/{userId}/$ref | 删除组所有者后，他们将不再是关联社区的管理员。 无法删除组) (用户 对象的最后一个所有者。 |
| 角色管理 | ||
| 获取Viva Engage中支持的角色类型的静态列表 | GET /employeeExperience/roles | 如果成功，此方法在 200 OK 响应正文中返回响应代码和角色列表。 |
| 获取具有特定Viva Engage角色的用户列表 | GET /employeeExperience/roles/{engagementRoleId}/members | 如果成功，此方法在 200 OK 响应正文中返回响应代码和参与角色成员列表。 |
| 获取分配给已登录用户的Viva Engage角色列表 | GET /me/employeeExperience/assignedRoles | 如果成功，此方法在 200 OK 响应正文中返回响应代码和角色列表。 |
| 获取分配给用户的Viva Engage角色列表 | GET /users/{userId}/employeeExperience/assignedRoles | 如果成功，此方法在 200 OK 响应正文中返回响应代码和角色列表。 |
| 向用户分配Viva Engage角色 | POST /employeeExperience/roles/{engagementRoleId}/members | 如果成功，此方法将Viva Engage角色分配给用户。 |
| 从用户中删除Viva Engage角色 | DELETE /employeeExperience/roles/{roleId}/members/{userId} | 如果成功，此方法将从用户撤消Viva Engage角色。 |
社区和组
对于本机模式下的Viva Engage网络，创建新的Viva Engage社区还会导致创建连接的 Microsoft 365 组，以及新的 SharePoint 网站、OneNote 笔记本和Planner计划。 使用关联的组管理社区上的作，例如：
- 添加或删除组成员
- 管理组所有权
- 删除组
- 重命名组
- 更新组说明
有关Viva Engage社区与Microsoft 365 个组之间的关系的详细信息，请参阅Viva Engage和Microsoft 365 组。
注意：不能使用创建组 API 来预配Viva Engage社区。
角色管理
Viva Engage支持基于角色的访问，方法是在平台中启用预定义的管理角色分配 (，例如网络管理员和已验证的管理员) 和企业通信角色。
这些可分配角色由Viva Engage预定义和管理。 无法创建或删除自定义角色。 有关详细信息，请参阅在 Viva Engage 中管理管理员角色。
Microsoft Entra角色通过 Microsoft Entra 管理中心进行管理，而可以使用 Viva Engage 平台和 Microsoft Graph API 分配和管理特定于Viva Engage的角色。 有关详细信息，请参阅Microsoft 365 管理中心指南。
API 限制
Viva Engage API 调用受速率限制的约束，允许每个用户、每个应用在 30 秒时间段内发出 10 个请求。 超过速率限制时，所有后续请求将返回 429 Too Many Requests 响应代码。
有关如何在 Microsoft Graph 中处理限制的指南，请参阅 Microsoft Graph 限制指南。
后续步骤
- 使用Microsoft图形 API管理Viva Engage中的社区和角色。
- 尝试在 Graph 资源管理器中Viva Engage API。