Использование API Graph Майкрософт для работы с Viva Engage

Microsoft API Graph позволяет приложениям управлять сообществами и ролями в Viva Engage. Viva Engage — это социальная структура для Набор Microsoft Viva приложений, которая объединяет людей в организации для обмена и обучения. Это место, где сотрудники могут общаться с лидерами, коллегами и сообществами, делиться своими знаниями и идеями, а также находить принадлежность на работе.

Важно!

API Viva Engage в Microsoft Graph поддерживается только для Viva Engage сетей в собственном режиме. Этот API нельзя использовать для управления устаревшими или внешними Viva Engage сетями.

Авторизация

Чтобы вызвать API Viva Engage в Microsoft Graph, приложению необходимо получить маркер доступа. Подробные сведения о маркерах доступа см. в статье Получение маркеров доступа для вызова Microsoft Graph. Приложению также требуются соответствующие разрешения. Дополнительные сведения см. в статье Справочник по разрешениям Microsoft Graph.

Основные варианты использования

В следующей таблице перечислены распространенные варианты использования API Viva Engage.

Вариант использования	API	Примечания
Создание сообщества	POST /employeeExperience/communities	В случае успешного 202 Accepted выполнения этот метод возвращает код ответа, содержащий ссылку на объект engagementAsyncOperation .
Опрос состояния создания сообщества	GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId}	В случае успешного выполнения этот метод возвращает код отклика 200 OK и объект engagementAsyncOperation в теле отклика. Периодически проверка состояние операции, выполняя запрос GET к этому расположению; подождите >30 секунд между проверками. После успешного завершения запроса состояние указывает succeeded , а resourceLocation указывает на созданный или измененный ресурс.
Получение сообщества после создания	GET /employeeExperience/community/{communityId}	В случае успешного выполнения этот метод возвращает код отклика 200 OK и объект community в тексте ответа. Объект community ссылается на связанный идентификатор группы Microsoft 365 , который можно использовать для управления членством в сообществе и владением.
Получение списка сообществ	GET /employeeExperience/communities	В случае успешного 200 OK выполнения этот метод возвращает код ответа и коллекцию объектов сообщества Viva Engage в теле отклика.
Обновление сообщества	PATCH /employeeExperience/community/{communityId}	В случае успешного выполнения этот метод обновляет существующее сообщество Viva Engage и возвращает 204 No Content код ответа.
Удаление сообщества	DELETE /employeeExperience/community/{communityId}	В случае успешного выполнения этот метод удаляет сообщество Viva Engage вместе со всем связанным содержимым Microsoft 365, включая подключенную группу Microsoft 365, записную книжку OneNote и планы Планировщик. Дополнительные сведения см. в статье Что произойдет при удалении Viva Engage сообщества, подключенного к группам Microsoft 365.
Добавление участников в сообщество	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 и плана Планировщик. Используйте связанную группу для управления операциями в сообществе, например:

• Добавление и удаление участников группы
• Управление владением группой
• Удаление группы
• Переименование группы
• Обновление описания группы

Дополнительные сведения о связях между Viva Engage сообществами и группами Microsoft 365 см. в разделе Viva Engage и Группы Microsoft 365.

Заметка: Вы не можете использовать API создания группы для подготовки Viva Engage сообщества.

Управление ролями

Viva Engage поддерживает доступ на основе ролей, включив назначение предопределенных административных ролей (таких как администратор сети и проверенный администратор) и ролей корпоративного взаимодействия на платформе.

Эти назначаемые роли предопределяются и управляются Viva Engage. Пользовательские роли нельзя создать или удалить. Дополнительные сведения см. в статье Управление ролями администратора в Viva Engage.

управление Microsoft Entra ролями осуществляется через Центр администрирования Microsoft Entra, а Viva Engage роли можно назначать и управлять ими с помощью платформы Viva Engage и API Microsoft Graph. Дополнительные сведения см. в руководстве по Центр администрирования Microsoft 365.

Ограничения API

Viva Engage вызовы API могут быть ограничены по скорости, что позволяет 10 запросов на пользователя на приложение в течение 30-секундного периода времени. При превышении предельной скорости все последующие запросы возвращают 429 Too Many Requests код ответа.

Инструкции по регулированию в Microsoft Graph см. в статье Руководство по регулированию Microsoft Graph.

Дальнейшие действия

• Используйте API Graph Майкрософт для управления сообществами и ролями в Viva Engage.
• Попробуйте API Viva Engage в Обозреватель Graph.