获取Microsoft Teams 机器人的上下文

项目
11/14/2023

重要

本文基于 v3 Bot Framework SDK。如果要查找 SDK 的当前文档 4.6 或更高版本，请参阅对话机器人部分。

机器人可以访问有关团队或聊天的其他上下文，例如用户配置文件。此信息可用于丰富机器人的功能，并提供更个性化的体验。

注意

Microsoft Teams 特定的机器人 API 最好通过 Bot Builder SDK 的扩展进行访问。
对于 C# 或 .NET，请下载 Microsoft.Bot.Connector.Teams NuGet 包。
对于 Node.js 开发，Bot Builder for Teams 功能已合并到 Bot Framework SDK v4.6 中。

提取团队名单

机器人可以查询团队成员列表及其基本配置文件。基本配置文件包括 Teams 用户 ID 和Microsoft Entra 信息，例如名称和对象 ID。可以使用此信息来关联用户标识。例如，检查通过 Microsoft Entra 凭据登录到选项卡的用户是否是团队成员。

REST API 示例

直接在上 /conversations/{teamId}/members/发出 GET 请求， serviceUrl 使用值作为终结点。

teamId可以在机器人在以下方案中接收的活动有效负载的对象中找到channeldata：

当用户在团队上下文中发送消息或与机器人交互时。有关详细信息，请参阅接收消息。
将新用户或机器人添加到团队时。有关详细信息，请参阅添加到团队的机器人或用户。

注意

调用 API 时，始终使用团队 ID。
该值 serviceUrl 往往稳定，但可能会更改。当新消息到达时，机器人必须验证其存储 serviceUrl 值。

GET /v3/conversations/19:ja0cu120i1jod12j@skype.net/members

Response body
[{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "objectId": "9d3e08f9-a7ae-43aa-a4d3-de3f319a8a9c",
    "givenName": "Larry",
    "surname": "Brown",
    "email": "Larry.Brown@fabrikam.com",
    "userPrincipalName": "labrown@fabrikam.com"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "johnp@fabrikam.com",
    "userPrincipalName": "johnp@fabrikam.com"
}, {
    "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"
}]

.NET 示例

使用 Team.Id 调用 GetConversationMembersAsync 以返回用户 ID 列表。调用 GetConversationMembersAsync 以获取 userRole 属性以用户身份返回值。

// Fetch the members in the current conversation
var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));
var teamId = context.Activity.GetChannelData<TeamsChannelData>().Team.Id;
var members = await connector.Conversations.GetConversationMembersAsync(teamId);

// Concatenate information about all members into a string
var sb = new StringBuilder();
foreach (var member in members.AsTeamsChannelAccounts())
{
    sb.AppendFormat(
        "GivenName = {0}, TeamsMemberId = {1}",
        member.Name, member.Id);

    sb.AppendLine();
}

// Post the member info back into the conversation
await context.PostAsync($"People in this conversation: {sb.ToString()}");

Node.js 或 TypeScript 示例


[...]
import * as builder from "botbuilder";
[...]

var teamId = session.message.sourceEvent.team.id;
connector.fetchMembers(
  (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is some error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

在个人或群组聊天中获取用户配置文件或名单

你可以对任何个人聊天进行 API 调用，以获取与机器人聊天的用户的个人资料信息。

API 调用、SDK 方法和响应对象与提取团队名单相同。唯一的区别是传递而不是 conversationIdteamId。

提取团队中的频道列表

机器人可以查询团队中的频道列表。

注意

默认常规频道的名称作为 null 返回，以允许本地化。
常规频道的频道 ID 始终与团队 ID 匹配。

REST API 示例

直接在上 /teams/{teamId}/conversations/发出 GET 请求， serviceUrl 使用值作为终结点。

的唯一源 teamId 是来自团队上下文的消息。该消息是来自用户的消息，或者是机器人在添加到团队时接收的消息。有关详细信息，请参阅添加到团队的机器人或用户。

注意

该值 serviceUrl 往往稳定，但可能会更改。当新消息到达时，机器人必须验证其存储 serviceUrl 值。

GET /v3/teams/19%3A033451497ea84fcc83d17ed7fb08a1b6%40thread.skype/conversations

Response body
{
    "conversations": [{
        "id": "19:033451497ea84fcc83d17ed7fb08a1b6@thread.skype",
        "name": null
    }, {
        "id": "19:cc25e4aae50746ecbb11473bba24c70a@thread.skype",
        "name": "Materials"
    }, {
        "id": "19:b7b84cba410c406ba671dbbf5e0a3519@thread.skype",
        "name": "Design"
    }, {
        "id": "19:fc5db2aed489454e8f8c06829ed6c986@thread.skype",
        "name": "Marketing"
    }]
}

.NET 示例

以下示例使用 FetchChannelList 来自 Bot Builder SDK for .NET 的 Teams 扩展的调用：

ConversationList channels = client.GetTeamsConnectorClient().Teams.FetchChannelList(activity.GetChannelData<TeamsChannelData>().Team.Id);

Node.js 示例

以下示例使用 fetchChannelList 来自 Bot Builder SDK for Node.js的 Teams 扩展的调用：

var teamId = session.message.sourceEvent.team.id;
connector.fetchChannelList(
  (session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is an error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

在机器人上下文中获取 clientInfo

可以在机器人的活动中提取 clientInfo。 clientInfo 包含以下属性：

Locale
国家/地区
平台
时区

JSON 示例

[
    {
        "type": "clientInfo",
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "Asia/Calcutta"
    }
]

C# 示例

var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));

{
    var clientinfo = context.Activity.Entities[0];
    await context.PostAsync($"ClientInfo: clientinfo ");
}

另请参阅

Bot Framework 示例。

通过

获取Microsoft Teams 机器人的上下文

提取团队名单

REST API 示例

.NET 示例

Node.js 或 TypeScript 示例

在个人或群组聊天中获取用户配置文件或名单

提取团队中的频道列表

REST API 示例

.NET 示例

Node.js 示例

在机器人上下文中获取 clientInfo

JSON 示例

C# 示例

另请参阅

其他资源