Изменения API-интерфейса бота Teams для получения участников команды или чата

Примечание.

Запущен процесс выведения из употребления API TeamsInfo.getMembers и TeamsInfo.GetMembersAsync. Изначально они массово отклоняют запросы в результате регулирования, ограничивая производительность пятью запросами в минуту, и возвращают не более 10 000 участников на команду. В результате, когда команда достигает определенного размера, полный ее список получить уже невозможно. Необходимо обновить пакет SDK Bot Framework до версии 4.10 или более поздней и переключиться на конечные точки API с разбивкой на страницы или API одного пользователя TeamsInfo.GetMemberAsync. Это относится и к вашему боту, даже если вы не используете эти API напрямую, так как старые пакеты SDK вызывают эти API при обработке события membersAdded. Список предстоящих изменений см. в разделе об изменениях API.

В настоящее время, если вы хотите получить информацию для одного или нескольких участников чата или команды, можно использовать API TeamsInfo.GetMembersAsyncбота Microsoft Teams для C#, TeamsInfo.getMembers TypeScript или Node.js API. Дополнительные сведения см. в разделе получение личного состава группы или пользовательского профиля.

Эти API имеют следующие недостатки:

  • Для больших групп их производительность низкая, а прерывание по истечении времени ожидания более вероятно. Максимальный размер рабочей группы значительно увеличился с момента выпуска Teams в начале 2017 г. Как GetMembersAsync или getMembers возвращает весь список участников, вызов API требует много времени, чтобы вернуться для больших команд, и для вызова обычно истекает время ожидания, и вам нужно повторить попытку.
  • Получить сведения о профиле для одного пользователя сложно. Чтобы получить сведения о профиле для одного пользователя, необходимо получить весь список участников, а затем найти нужный. В пакете SDK Для Bot Framework есть вспомогательная функция, которая упрощает ее, но она не эффективна.

С появлением команд для всей организации необходимо лучше согласовать эти API с элементами управления конфиденциальностью Microsoft 365. Боты, используемые в больших группах, могут получать основные сведения о профиле пользователя аналогично разрешению User.ReadBasic.All Microsoft Graph. Администраторы клиентов имеют значительную степень контроля над тем, какие приложения и боты можно использовать в клиенте, но эти параметры отличаются от Microsoft Graph.

Этот фрагмент кода представляет собой пример JSON-представления того, что возвращают боты API Teams:

[{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "name": "Anon1 (Guest)",
    "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
 "userRole": "anonymous"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "johnp@fabrikam.com",
    "userPrincipalName": "johnp@fabrikam.com",
    "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
 "userRole": "user"
}, {
    "id": "29:1URzNQM1x1PNMr1D7L5_lFe6qF6gEfAbkdG8_BUxOW2mTKryQqEZtBTqDt10-MghkzjYDuUj4KG6nvg5lFAyjOLiGJ4jzhb99WrnI7XKriCs",
    "objectId": "6b7b3b2a-2c4b-4175-8582-41c9e685c1b5",
    "givenName": "Rick",
    "surname": "Stevens",
    "email": "Rick.Stevens@fabrikam.com",
    "userPrincipalName": "rstevens@fabrikam.com",
    "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
 "userRole": "user"
}]

Изменения API

Ниже описаны предстоящие изменения API:

  • Для получения сведений о профиле для участников чата или группы TeamsInfo.GetPagedMembersAsync создается новый API. Этот API теперь доступен в пакете SDK Bot Framework начиная с версии 4.8. Для разработки во всех остальных версиях используйте метод GetConversationPagedMembers.

Примечание.

Обновите пакет SDK для Microsoft Bot Framework до последней версии следующим образом:

  • Пакет SDK Bot Framework версии 3: обновление до версии 3.30.2 или более поздней.
  • Пакет SDK Bot Framework версии 4: обновление до версии 4.8 или более поздней.
  • Для получения сведений о профиле одного пользователя TeamsInfo.GetMemberAsync создается новый API. Он принимает идентификатор команды или чата и имя участника-пользователя, то есть userPrincipalName, Microsoft Entra идентификатор objectIdобъекта или идентификатор id пользователя Teams в качестве параметров и возвращает сведения о профиле для этого пользователя.

    Примечание.

    objectId заменяется на aadObjectId в соответствии с тем, что вызывается в объекте сообщения Activity Bot Framework. Новый API доступен начиная с версии 4.8 пакета SDK Bot Framework. Он также доступен в расширении Пакета SDK Bot Framework Teams 3.x. Тем временем вы можете использовать конечную точку REST.

  • TeamsInfo.GetMembersAsync в C# и TeamsInfo.getMembers в TypeScript или Node.js официально не рекомендуется к использованию. После того как новый API станет доступен, вам придется обновить все боты, чтобы использовать его. Это также относится к базовому REST API, который используется этими API.

  • К концу 2022 года боты не смогут заранее получать свойства userPrincipalName и email участников чата или группы. Боты должны использовать API Graph для получения необходимых сведений. Новый API GetConversationPagedMembers утратит возможность возвращать свойства userPrincipalName и emailв конце 2022 года.

    Примечание.

    Для получения сведений рекомендуется использовать API Graph с маркером доступа.

См. также