使用 Microsoft 图形 API 与 Viva Engage 配合使用
重要
Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。
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 网络，创建新的 Viva Engage 社区还会导致创建连接的 Microsoft 365 组，以及新的 SharePoint 网站、OneNote 笔记本和 Planner 计划。 使用关联的组管理社区上的操作，例如：
- 添加或删除组成员
- 管理组所有权
- 删除组
- 重命名组
- 更新组说明
有关 Viva Engage 社区与 Microsoft 365 组之间的关系的详细信息，请参阅 Viva Engage 和 Microsoft 365 组。
注意： 不能使用 创建组 API 来预配 Viva Engage 社区。
API 限制
Viva Engage API 调用受速率限制的约束，允许每个用户、每个应用在 30 秒时间段内发出 10 个请求。 超过速率限制时，所有后续请求将返回 429 Too Many Requests 响应代码。
有关如何在 Microsoft Graph 中处理限制的指南，请参阅 Microsoft Graph 限制指南。
后续步骤
- 使用 Microsoft Graph API 管理 Viva Engage 中的社区。
- 在 Graph 资源管理器中试用 Viva Engage API。