获取机器人的 Teams 特定上下文

  • 项目

重要

本部分中的代码示例基于 Bot Framework SDK 版本 4.6 和更高版本。 如果要查找早期版本的文档，请参阅文档的旧版 SDK 文件夹中的 机器人 - v3 SDK 部分。

机器人可以访问有关安装它的团队或聊天的其他上下文数据。 此信息可用于丰富机器人的功能并提供更个性化的体验。

提取名单或用户个人资料

机器人可以查询成员列表及其基本用户配置文件，包括 Teams 用户 ID 和Microsoft Entra信息，如名称和 objectId。 可以使用此信息来关联用户标识。 例如，若要检查通过Microsoft Entra凭据登录到选项卡的用户是否为团队成员。 对于获取对话成员，最小或最大页面大小取决于实现。 小于 50 的页面大小被视为 50，大于 500 的页面大小上限为 500。 即使使用非分页版本，它在大型团队中也不可靠，不得使用。 有关详细信息，请参阅 Teams 机器人 API 在提取团队或聊天成员方面的更改。

注意

  • 分页在团队和频道中可用。
  • 聊天中不支持分页。 对于聊天，始终返回整个名单。

以下示例代码使用分页终结点提取名单：

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var members = new List<TeamsChannelAccount>();
        string continuationToken = null;

        do
        {   
            // Gets a paginated list of members of one-on-one, group, or team conversation.
            var currentPage = await TeamsInfo.GetPagedMembersAsync(turnContext, 100, continuationToken, cancellationToken);
            continuationToken = currentPage.ContinuationToken;
            members.AddRange(currentPage.Members);
         }
         while (continuationToken != null);
     }
}

提取名单或用户个人资料后，可以获取单个成员的详细信息。 目前，若要检索聊天或团队的一个或多个成员的信息，请使用 Microsoft Teams 机器人 API TeamsInfo.GetMembersAsync（对于 C#）或 TeamsInfo.getMembers（对于 TypeScript API）。

获取单个成员详细信息

还可以使用其 Teams 用户 ID、UPN 或Microsoft Entra对象 ID 检索特定用户的详细信息。

以下示例代码用于获取单个成员详细信息：

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {   
        // Gets the account of a single conversation member.
        // This works in one-on-one, group, and team scoped conversations.
        var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
    }
}

获取单个成员的详细信息后，可以获取团队的详细信息。 目前，要检索团队的信息，请使用适用于 C# 的 Teams 机器人 API TeamsInfo.GetMemberDetailsAsync 或适用于 TypeScript 的 Teams 机器人 API TeamsInfo.getTeamDetails。

获取团队的详细信息

在团队中安装后，机器人可以查询有关该团队的元数据，包括Microsoft Entra组 ID。

以下示例代码用于获取团队的详细信息：

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Gets the details for the given team id. This only works in team scoped conversations.
        // TeamsGetTeamInfo: Gets the TeamsInfo object from the current activity.
        TeamDetails teamDetails = await TeamsInfo.GetTeamDetailsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
        if (teamDetails != null) {
            await turnContext.SendActivityAsync($"The groupId is: {teamDetails.AadGroupId}");
        }
        else {
            // Sends a message activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync($"Message did not come from a channel in a team.");
        }
    }
}

获取团队的详细信息后，可以获取团队中的频道列表。 目前，要检索团队中频道列表的信息，请使用适用于 C# 的 Teams 机器人 API TeamsInfo.GetTeamChannelsAsync 或适用于 TypeScript API 的 TeamsInfo.getTeamChannels。

获取团队中的频道列表

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

注意

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

以下示例代码用于获取团队中的频道列表：

public class MyBot : TeamsActivityHandler
{
    // Override this in a derived class to provide logic specific to Message activities.
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Returns a list of channels in a Team. This only works in team scoped conversations.
        IEnumerable<ChannelInfo> channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"The channel count is: {channels.Count()}");
    }
}

Teams 机器人示例

代码示例

有关演示该功能的完整工作示例，请参阅 Bot Framework 的以下 Teams 示例：

示例名称 说明 .NET Node.js Python 清单
Teams 对话自动程序 此示例演示如何将机器人框架 v4 中提供的不同机器人对话事件用于个人和团队范围。 View View View View
使用 OAuthPrompt 进行身份验证 此示例演示 Bot Framework v4 中的身份验证和基本消息传送。 View View View View
Teams 文件上传 此示例演示如何在一对一对话中将文件与机器人一起使用。 View View View View
对话 (TeamsJS v1.x) 中称为任务模块 此示例演示如何对消息扩展使用对话框中的卡片中的值。 View View View View
在频道中启动新线程 此示例演示如何使用机器人在通道中使用新线程。 View View View View
Teams 应用本地化 此示例演示如何使用机器人和选项卡使用 Teams 应用本地化。 View View 不适用 View

后续步骤

使用机器人发送和接收文件

另请参阅