Изменения в API-интерфейсах ленты Teams для извлечения участников группы или чатаChanges to Teams Bot APIs for Fetching Team/Chat Members

В настоящее время разработчики-роботы, желающие получить информацию для одного или нескольких участников беседы или команды, используют API Microsoft Teams Bot TeamsInfo.GetMembersAsync (для C#) или TeamsInfo.getMembers (для TypeScript/Node.js), описанные здесь.Currently, bot developers who want to retrieve information for one or more members of a chat or team use the Microsoft Teams bot APIs TeamsInfo.GetMembersAsync (for C#) or TeamsInfo.getMembers (for TypeScript/Node.js) APIs (documented here). В настоящее время эти API имеют несколько недостатков:These APIs have several shortcomings today:

  • В крупных командах производительность снижается, и время ожидания может быть больше.For large teams, performance is poor and timeouts are more likely. Максимальный размер команды значительно увеличился с момента выпуска Microsoft Teams на ранних 2017.The maximum team size has grown considerably since Microsoft Teams was released in early 2017. Так как GetMembersAsync / getMembers возвращает весь список элементов, он занимает много времени, чтобы вызов API возвращался для крупных команд, и вы можете попробовать еще раз.Since GetMembersAsync/getMembers returns the entire member list, it takes a long time for the API call to return for large teams, and it’s not uncommon for the call to time out and you have to try again.
  • Получить сведения о профиле для отдельного пользователя очень трудоемко.Getting profile details for a single user is cumbersome. Чтобы получить сведения о профиле для одного пользователя, необходимо извлечь весь список участников, а затем выполнить поиск нужного пользователя.To get the profile information for a single user, you have to retrieve the entire member list and then search for the one you want. True, существует вспомогательная функция в пакете SDK Bot для упрощения, но в этом случае она неэффективна.True, there’s a helper function in the Bot Framework SDK to make it simpler, but under the covers it’s not efficient.

Как и в случае с введением групп по всей Организации, мы осознали, что имелось время для более точного выравнивания этих API с помощью Office 365: Боты, используемые в крупных командах, могут получать основные сведения о профиле, аналогичные User.ReadBasic.All разрешениям Microsoft Graph.Separately, with the introduction of org-wide teams, we realized it was time to better align these APIs with Office 365 privacy controls: bots used in large teams are able to retrieve basic profile information, which is similar to the User.ReadBasic.All Microsoft Graph permission. Администраторы клиентов имеют большой контроль над тем, какие приложения и боты можно использовать в клиенте, но эти параметры отличаются от тех, которые управляют Microsoft Graph.Tenant administrators have a great deal of control over which apps and bots can be used in their tenant, but these settings are different than the ones governing Microsoft Graph.

Ниже показан пример представления JSON, который возвращается этими API на сегодняшний день.Here’s a sample JSON representation of what’s returned by these APIs today. Ниже приведены некоторые из этих полей.I’ll refer to some of the fields below.

[{
    "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"
}]

Изменения APIAPI Changes

Ниже приведены будущие изменения API:Here are the upcoming API changes:

  • Мы создали новый API TeamsInfo.GetPagedMembersAsync для получения сведений о профиле участников беседы или команды.We've created a new API TeamsInfo.GetPagedMembersAsync for retrieving profile information for members of a chat/team. Этот API теперь доступен в пакете SDK для Bot Framework 4,8.This API is now available with the Bot Framework 4.8 SDK. Для разработки во всех остальных версиях используется GetConversationPagedMembers метод.For development in all other versions use the GetConversationPagedMembers method. Примечание : в V3 или v4 лучше всего выполнить обновление до последней версии пункта (3.30.2 или 4,8 соответственно).Note : In either v3 or v4, the best action is to upgrade to the latest point release (3.30.2 or 4.8 respectively).
  • Мы создали новый API TeamsInfo.GetMemberAsync для получения сведений о профиле для одного пользователя.We've created a new API TeamsInfo.GetMemberAsync for retrieving the profile information for a single user. Он принимает идентификатор группы или чата, а также имя участника-пользователя ( userPrincipalName , см. выше ), идентификатор объекта Azure Active Directory (, см. выше) objectId или идентификатор пользователя Teams (см see above id . выше ) в качестве параметров и возвращает сведения о профиле для этого пользователя.It takes the ID of the team/chat and a UPN (userPrincipalName, see above ), Azure Active Directory Object ID (objectId, see above ), or the Teams user ID (id, see above ) as parameters and returns the profile information for that user. Примечание : мы изменим в соответствии с тем, objectId aadObjectId что вызывается в Activity объекте сообщения Bot Framework.Note : We're changing objectId to aadObjectId to match what it's called in the Activity object of a Bot Framework message. Новый API доступен в версии 4,8 с пакетом SDK для Bot.The new API is available with version 4.8 of the Bot Framework SDK. Он скоро будет доступен в версии пакета SDK для Teams (Bot) для Team Framework 3. x, а также в то же время вы можете использовать конечную точку REST .It will soon be available in the Teams SDK extension Bot Framework 3.x as well; meanwhile you can use the REST endpoint.
  • TeamsInfo.GetMembersAsync (C#) и TeamsInfo.getMembers (TypeScript/Node.js) формально формально и больше не работает в поздних 2021.TeamsInfo.GetMembersAsync (C#) and TeamsInfo.getMembers (TypeScript/Node.js) is formally deprecated and will stop working in late 2021. Мы будем объявлять о конкретном расписание в 2020 мая, основываясь на отзывах разработчиков.We'll announce a specific timetable in May 2020, based on feedback from developers. После того, как новые постраничные API будут доступны, разработчикам следует обновить свои Боты, чтобы использовать ее.Once the new paged API is available, developers should update their bots to use it. (Это также относится к базовым API REST, которые используются этими API).(This also applies to the underlying REST API these APIs use.)
  • С опозданием 2021 Боты не сможет получить доступ к userPrincipalName email свойствам участников разговора или рабочей группы и будет использовать Microsoft Graph для их извлечения.By late 2021, bots will not be able to proactively retrieve the userPrincipalName or email properties for members of a chat/team and will need to use Microsoft Graph to retrieve them. В частности, userPrincipalName и email свойства не будут возвращены из нового GetConversationPagedMembers API, начиная с позднего 2021.Specifically, userPrincipalName and email properties won't be returned from the new GetConversationPagedMembers API starting in late 2021. Для получения этих сведений Боты должен использовать Microsoft Graph с маркером доступа.Bots will have to use Microsoft Graph with an access token to retrieve this information. Очевидно, что это существенное изменение: мы должны упростить, чтобы Боты получить маркер доступа, и мы должны упростить и упростить процесс разрешения конечных пользователей.This is obviously a major change: We must make it easier for bots to get an access token, and we must streamline and simplify the end-user consent process.

Отзывы и дополнительные сведенияFeedback and More Information

Мы будем использовать эту страницу для предоставления актуальной информации об этих изменениях.We'll use this page for providing up to date information on these changes. Если у вас возникнут вопросы, используйте "Отправить Отзывы > на этой странице" в разделе отзывов , приведенном ниже.If you have questions, use the "Send feedback > on this page" in the Feedback section below.