获取 Microsoft Teams 机器人的上下文

  • 项目

重要

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

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

注意

  • 最好通过 Bot Builder SDK 的扩展访问特定于 Microsoft Teams 的机器人 API。
  • 对于 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 示例。