Teams 机器人 API 在提取团队或聊天成员方面的更改

  • 项目

注意

TeamsInfo.getMembers 和 TeamsInfo.GetMembersAsync API 的弃用过程已启动。 最初，它们被严格限制为每分钟 5 个请求，并且每个团队最多返回 1 万个成员。 这导致随着团队规模的增加，不会返回完整的名单。 必须更新到 Bot Framework SDK 版本 4.10 或更高版本，并切换到分页 API 终结点或 TeamsInfo.GetMemberAsync 单用户 API。 即使未直接使用这些 API，这也适用于你的机器人，因为旧版 SDK 在 membersAdded 事件期间会调用这些 API。 若要查看即将进行的更改的列表，请参阅 API 更改。

目前，如果要检索聊天或团队的一个或多个成员的信息，可以使用适用于 C# 或 TypeScript 或 TeamsInfo.getMembers Node.js API 的 Microsoft Teams 机器人TeamsInfo.GetMembersAsync API。 有关详细信息，请参阅提取名单或用户个人资料。

这些 API 有以下缺点：

  • 对于大型团队，性能较差且超时的可能性更大：自 2017 年初发布 Teams 以来，最大团队规模已大幅增加。 作为 GetMembersAsync 或 getMembers 返回整个成员列表，对于大型团队，API 调用需要很长时间才能返回，并且调用超时很常见，必须重试。
  • 获取单个用户的配置文件详细信息很困难：若要获取单个用户的配置文件信息，必须检索整个成员列表，然后搜索所需的成员列表。 Bot Framework SDK 中有一个帮助程序函数，可使其更简单，但效率不高。

随着组织范围的团队的引入，需要更好地使这些 API 与 Microsoft 365 隐私控制保持一致。 大型团队中使用的机器人能够检索类似于 User.ReadBasic.All Microsoft Graph 权限的基本个人资料信息。 租户管理员可以很好地控制哪些应用和机器人可在其租户中使用，但这些设置不同于 Microsoft Graph。

以下代码提供 Teams 机器人 API 返回的内容的示例 JSON 表示形式：

[{
    "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 更改：

注意

升级到最新版本的 Microsoft Bot Framework SDK，如下所示：

  • Bot Framework SDK v3：升级到版本 3.30.2 或更高版本。
  • Bot Framework SDK v4：升级到版本 4.8 或更高版本。

  • 将创建新 API TeamsInfo.GetMemberAsync，用于检索单个用户的个人资料信息。 它采用团队或聊天的 ID 和 UPN（Microsoft Entra userPrincipalName对象 ID objectId或 Teams 用户 IDid）作为参数，并返回该用户的个人资料信息。

    注意

    objectId 更改为 aadObjectId 以匹配 Bot Framework 消息的 Activity 对象中调用的内容。 新 API 适用于版本 4.8 或更高版本的 Bot Framework SDK。 它还可在 Teams SDK 扩展 Bot Framework 3.x 中使用。 同时，可以使用 REST 终结点。

  • C# 中的 TeamsInfo.GetMembersAsync 和 TypeScript 或 Node.js 中的 TeamsInfo.getMembers 已正式弃用。 新 API 可用后，必须更新机器人才能使用它。 这也适用于这些 API 使用的基础 REST API。

  • 到 2022 年底，机器人无法主动检索聊天或团队成员的 userPrincipalName 或 email 属性。 机器人必须使用 Graph API 来检索所需的信息。 从 2022 年末开始，新 GetConversationPagedMembers API 无法返回 userPrincipalName 和 email 属性。

    注意

    建议将图形 API与访问令牌一起使用来检索信息。

另请参阅