Интеграция средства "Выбор людей"

"Выбор людей" — это входной контроль в Teams, позволяющий пользователям искать и выбирать пользователей. Вы можете интегрировать элемент управления вводом в средство "Выбор людей" в веб-приложении, что позволит конечным пользователям выполнять различные функции, такие как поиск и выбор пользователей в чате, канале или в организации в Teams. Элемент управления "Выбор людей" доступен во всех клиентах Teams, таких как веб-приложения, настольные компьютеры и мобильные устройства.

Вы можете использовать клиентскую библиотеку JavaScript в Microsoft Teams, которая предоставляет selectPeople API для интеграции элемента управления ввода Люди Picker в веб-приложение.

Преимущества использования средства "Выбор людей"

• Работает со всеми возможностями Teams, такими как диалоговое окно (называется модулем задач в TeamsJS версии 1.x), чат, канал, вкладка собрания и личное приложение.
• Позволяет пользователю искать и выбирать пользователей в чате, канале или всей организации в Teams.
• Помогает в сценариях, связанных с назначением задач, добавлением тегов и уведомлением пользователя.
• Экономит значительное время и усилия по сравнению с созданием аналогичного элемента управления.

Чтобы интегрировать управление вводом в средство "Выбор людей" в приложении Teams, используйте API selectPeople. Для интеграции и вызова API необходимо хорошо знать прилагаемый фрагмент кода. Кроме того, вам необходимо ознакомиться с ошибками ответов API.

API selectPeople

API selectPeople позволяет добавлять в веб-приложения элемент управления вводом в средстве "Выбор людей" в Teams, а также помогает со следующими задачами.

• Позволяет пользователю искать и выбирать одного или несколько пользователей из списка.
• Возвращает в веб-приложение идентификатор, имя и адрес электронной почты выбранных пользователей.

В личном приложении элемент управления ищет имя или идентификатор электронной почты по всей организации в Teams. Если приложение добавляется в чат или канал, контекст поиска настраивается в зависимости от сценария. Поиск ограничен участниками чата или канала.

API selectPeople поставляется со следующими конфигурациями ввода:

Параметр конфигурации	Тип	Описание	Значение по умолчанию
title	String	Это необязательный параметр, который задает заголовок для элемента управления "Выбор людей".	selectPeople
setSelected	String	Это необязательный параметр. Вы должны передать Microsoft Entra идентификаторы людей, которые будут предварительно избраны. Этот параметр предварительно выбирает людей при запуске элемента управления вводом средства "Выбор людей". В единичном выборе предварительно заполняется только первый действительный пользователь, остальные игнорируются.	Null
openOrgWideSearchInChatOrChannel	Логическое	Это необязательный параметр, и если задано значение true, он запускает "Выбор людей" в масштабах всей организации, даже если приложение добавлено в чат или канал.	False
singleSelect	Логическое	Это необязательный параметр, и если задано значение true, он запускает "Выбор людей" и ограничивает выбор только одним пользователем.	False

На следующем изображении показан интерфейс средства "Выбор людей" на мобильных и настольных компьютерах.

Мобильные устройства

С помощью элемента управления вводом средства "Выбор людей" пользователь может искать и добавлять пользователей, следуя следующим инструкциям.

1. Введите имя пользователя. Появится список с предложениями имен.

2. Выберите имя нужного пользователя из списка.

   

Компьютер

Элемент управления "Выбор людей" в Интернете или в настольной версии запускается в модальном окне поверх веб-приложения. Чтобы добавить пользователей, выполните следующие действия.

1. Введите имя пользователя. Появится список с предложениями имен.

2. Выберите имя нужного пользователя из списка.

   

Фрагмент кода

В следующем фрагменте кода показано использование пользователей API selectPeople из списка:

TeamsJS версии 2

people.selectPeople({ setSelected: ["aad id"], openOrgWideSearchInChatOrChannel: true, singleSelect: false, title: true}).then(people) => 
 {
    output(" People length: " + people.length + " " + JSON.stringify(people));
 }).catch((error) => { /*Unsuccessful operation*/ });

TeamsJS версии 1

people.selectPeople((error: microsoftTeams.SdkError, people: microsoftTeams.people.PeoplePickerResult[]) => 
 {
    if (error) 
    {
        if (error.message) 
           {
             alert(" ErrorCode: " + error.errorCode + error.message);
           }
            else 
            {
              alert(" ErrorCode: " + error.errorCode);
            }
      }
    if (people)
     {
            output(" People length: " + people.length + " " + JSON.stringify(people));
      }
  },{ setSelected: ["aad id"], openOrgWideSearchInChatOrChannel: true, singleSelect: false, title: true});

Обработка ошибок

В следующей таблице перечислены коды ошибок и их описания.

Код ошибки	Название ошибки	Описание
100	NOT_SUPPORTED_ON_PLATFORM	API не поддерживается на текущей платформе.
500	INTERNAL_ERROR	Внутренняя ошибка при запуске средства "Выбор людей".
4000	INVALID_ARGUMENTS	API вызывается с неправильными или недостаточными обязательными аргументами.
8000	USER_ABORT	Пользователь отменил операцию.
9000	OLD_PLATFORM	Пользователь использует старую сборку платформы, где реализация API недоступна. Чтобы устранить проблему, обновите сборку до последней версии.

Пример кода

Название примера	Описание	.NET	Node.js	Манифест
Средство выбора людей на вкладке	В этом примере показана функция выбора людей с помощью клиентского пакета SDK teams js внутри вкладки.	Просмотр	Просмотр	Просмотр

Дополнительные ресурсы

• Интеграция веб-приложений
• Интеграция возможностей мультимедиа
• Интеграция функции сканирования QR- или штрихкода в Teams
• Интеграция функций местонахождения
• Люди компонент средства выбора в наборе средств Microsoft Graph