智能机器人活动处理程序

本文档基于机器人如何在核心Bot Framework 中运行文档中的文章生成。 为 Microsoft Teams 开发的机器人与核心 Bot Framework 之间的主要区别在于 Teams 中提供的功能。

活动处理程序用于组织机器人的对话逻辑。 使用 Teams 活动处理程序和机器人逻辑以两种方式处理活动。 Teams 活动处理程序添加了对 Teams 特定事件和交互的支持。 机器人对象包含轮次的会话推理或逻辑，并公开轮次处理程序，该处理程序是可以接受来自机器人适配器的传入活动的方法。

Teams 活动处理程序

Teams 活动处理程序派生自 Microsoft Bot Framework 的活动处理程序。 它会先路由所有 Teams 活动，然后再允许处理任何非 Teams 特定的活动。

当 Teams 机器人收到活动时，该活动将路由到活动处理程序。 所有活动都通过一个称为轮次处理程序的基本处理程序进行路由。 轮次处理程序调用所需的活动处理程序来管理收到的任何活动。 Teams 机器人派生自 TeamsActivityHandler 类，此类派生自 Bot Framework 的 ActivityHandler 类。

注意

如果机器人活动处理时间超过 15 秒，Teams 会向机器人终结点发送重试请求。 因此，机器人中会出现重复的请求。

C#

机器人是使用 Bot Framework 创建的。 如果机器人收到消息活动，则轮次处理程序会收到此传入活动的通知。 然后，轮次处理程序将传入活动发送到 OnMessageActivityAsync 活动处理程序。 在 Teams 中，此功能保持不变。 如果机器人收到会话更新活动，轮次处理程序将收到该传入活动的通知，并将传入活动发送到 OnConversationUpdateActivityAsync。 Teams 活动处理程序首先检查任何 Teams 特定的事件。 如果未找到任何事件，则会将其传递到 Bot Framework 的活动处理程序。

在 Teams 活动处理程序类中，有两个主要的 Teams 活动处理程序， OnConversationUpdateActivityAsync 和 OnInvokeActivityAsync。 OnConversationUpdateActivityAsync 路由所有会话更新活动， OnInvokeActivityAsync 路由所有 Teams 调用活动。

如果要实现特定活动处理程序 Teams 逻辑，必须覆盖机器人中的方法，如机器人逻辑部分所示。 这些处理程序没有基本实现。 因此，请在替代中添加所需的逻辑。

Teams 活动处理程序的代码片段：

OnTeamsChannelCreatedAsync

protected override Task OnTeamsChannelCreatedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            // Code logic here
        }

OnTeamsChannelDeletedAsync

protected override Task OnTeamsChannelDeletedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            // Code logic here
        }

OnTeamsChannelRenamedAsync

protected override Task OnTeamsChannelRenamedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsTeamRenamedAsync

protected override Task OnTeamsTeamRenamedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsMembersAddedAsync

protected override Task OnTeamsMembersAddedAsync(IList<TeamsChannelAccount> teamsMembersAdded, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsMembersRemovedAsync

protected override Task OnTeamsMembersRemovedAsync(IList<TeamsChannelAccount> teamsMembersRemoved, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken);
  {
   // Code logic here
  }

OnTeamsMessageEditAsync

protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
  { 
   // Code logic here 
  } 

OnTeamsMessageUndeleteAsync

protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
  { 
   // Code logic here 
  } 

OnTeamsMessageSoftDeleteAsync

 protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken)
  { 
   // Code logic here 
  } 

JavaScript

机器人是使用 Bot Framework 创建的。 如果机器人收到消息活动，则轮次处理程序会收到此传入活动的通知。 然后，轮次处理程序将传入活动发送到 onMessage 活动处理程序。 在 Teams 中，此功能保持不变。 如果机器人收到会话更新活动，轮次处理程序将收到该传入活动的通知，并将传入活动发送到 dispatchConversationUpdateActivity。 Teams 活动处理程序首先检查任何 Teams 特定的事件。 如果未找到任何事件，则会将其传递到 Bot Framework 的活动处理程序。

在 Teams 活动处理程序类中，有两个主要的 Teams 活动处理程序， dispatchConversationUpdateActivity 和 onInvokeActivity。 dispatchConversationUpdateActivity 路由所有会话更新活动， onInvokeActivity 路由所有 Teams 调用活动。

如果要实现特定活动处理程序 Teams 逻辑，必须覆盖机器人中的方法，如机器人逻辑部分所示。 为这些处理程序定义机器人逻辑，然后确保在最后调用 next()。 通过调用 next()，可确保运行下一个处理程序。

Teams 活动处理程序的代码片段：

onTeamsChannelCreated

onTeamsChannelCreated(async (channelInfo, teamInfo, context, next) => {
       // code for handling
        await next()
    });

onTeamsChannelDeleted

onTeamsChannelDeleted(async (channelInfo, teamInfo, context, next) => {
       // code for handling
       await next()
    });

onTeamsChannelRenamed

onTeamsChannelRenamed(async (channelInfo, teamInfo, context, next) => {
       // code for handling
       await next()
    });

onTeamsTeamRenamed

onTeamsTeamRenamedAsync(async (teamInfo, context, next) => {
       // code for handling
       await next()
    });

onTeamsMembersAdded

onTeamsMembersAdded(async (membersAdded, teamInfo, context, next) => {
       // code for handling
    await next();
    });

onTeamsMembersRemoved

onTeamsMembersRemoved(async (membersRemoved, teamInfo, context, next) => {
       // code for handling
    await next();
    });

Python

机器人是使用 Bot Framework 创建的。 如果机器人收到消息活动，则轮次处理程序会收到此传入活动的通知。 然后，轮次处理程序将传入活动发送到 on_message_activity 活动处理程序。 在 Teams 中，此功能保持不变。 如果机器人收到会话更新活动，轮次处理程序将收到该传入活动的通知，并将传入活动发送到 on_conversation_update_activity。 Teams 活动处理程序首先检查任何 Teams 特定的事件。 如果未找到任何事件，则会将其传递到 Bot Framework 的活动处理程序。

在 Teams 活动处理程序类中，有两个主要的 Teams 活动处理程序， on_conversation_update_activity 和 on_invoke_activity。 on_conversation_update_activity 路由所有会话更新活动， on_invoke_activity 路由所有 Teams 调用活动。

如果要实现特定活动处理程序 Teams 逻辑，必须覆盖机器人中的方法，如机器人逻辑部分所示。 这些处理程序没有基本实现。 因此，请在替代中添加所需的逻辑。

机器人逻辑

机器人逻辑处理来自一个或多个机器人通道的传入活动，并在响应中生成传出活动。 从 Teams 活动处理程序类派生的机器人仍然如此，该类首先检查 Teams 活动。 检查 Teams 活动后，会将所有其他活动传递给 Bot Framework 的活动处理程序。

C#

核心 Bot Framework 处理程序

注意

• 除已添加和已删除成员的活动外，本部分中介绍的所有活动处理程序继续与非 Teams 机器人一样运行。
• onInstallationUpdateActivityAsync() 方法用于在将机器人添加到 Teams 时获取 Teams 区域设置。

活动处理程序在团队的上下文中有所不同，其中新成员将添加到团队而不是消息线程。

中 ActivityHandler 定义的处理程序列表包括以下事件：

Event	处理程序	说明
收到的任何活动类型	OnTurnAsync	此方法根据收到的活动类型调用其他处理程序之一。
收到的消息活动	OnMessageActivityAsync	可以重写此方法来处理 Message 活动。
收到的消息更新活动	OnMessageUpdateActivityAsync	可以重写此方法来处理消息更新活动。
收到的邮件删除活动	OnMessageDeleteActivityAsync	可以重写此方法来处理消息删除活动。
收到的对话更新活动	OnConversationUpdateActivityAsync	如果机器人以外的成员已加入或离开对话，则此方法在活动上 ConversationUpdate 调用处理程序。
非机器人成员加入了对话	OnMembersAddedAsync	可以重写此方法来处理加入会话的成员。
非机器人成员离开了对话	OnMembersRemovedAsync	可以重写此方法来处理离开会话的成员。
收到的事件活动	OnEventActivityAsync	此方法在 Event 活动上调用特定于事件类型的处理程序。
收到的令牌响应事件活动	OnTokenResponseEventAsync	可以重写此方法来处理令牌响应事件。
收到的非令牌响应事件活动	OnEventAsync	可以重写此方法来处理其他类型的事件。
收到的其他活动类型	OnUnrecognizedActivityTypeAsync	可以重写此方法以处理任何未处理的活动类型。

Teams 特定的活动处理程序

扩展 TeamsActivityHandler 核心 Bot Framework 处理程序节中的处理程序列表，以包括以下事件：

Event	处理程序	说明
channelCreated	OnTeamsChannelCreatedAsync	可以重写此方法来处理正在创建的 Teams 频道。 有关详细信息，请参阅在对话更新事件中创建的通道。
ChannelDeleted	OnTeamsChannelDeletedAsync	可以重写此方法来处理要删除的 Teams 频道。 有关详细信息，请参阅对话更新事件中已删除的通道。
channelRenamed	OnTeamsChannelRenamedAsync	可以重写此方法以处理要重命名的 Teams 频道。 有关详细信息，请参阅对话更新事件中重命名的通道。
teamRenamed	OnTeamsTeamRenamedAsync	return Task.CompletedTask; 可以重写此方法来处理要重命名的 Teams 团队。 有关详细信息，请参阅在对话更新事件中重命名的团队。
MembersAdded	OnTeamsMembersAddedAsync	此方法调用 ActivityHandler 中的 OnMembersAddedAsync 方法。 可以重写此方法来处理加入团队的成员。 有关详细信息，请参阅对话更新事件中添加的团队成员。
MembersRemoved	OnTeamsMembersRemovedAsync	此方法调用 ActivityHandler 中的 OnMembersRemovedAsync 方法。 可以重写该方法来处理离开团队的成员。 有关详细信息，请参阅对话更新事件中删除的团队成员。
messageEdit	OnTeamsMessageEditAsync	可以重写此方法来处理 Teams 消息编辑事件。
messageUndelete	OnTeamsMessageUndeleteAsync	可以重写此方法以处理 Teams 消息取消删除事件。
messageSoftDelete	OnTeamsMessageSoftDeleteAsync	可以重写此方法来处理 Teams 消息软删除事件。

Teams 调用活动

从 Teams 活动处理程序调用的 OnInvokeActivityAsync Teams 活动处理程序列表包括以下调用类型：

调用类型	处理程序	说明
CardAction.Invoke	OnTeamsCardActionInvokeAsync	当连接器收到卡片操作调用活动时，将调用此方法。
fileConsent/invoke	OnTeamsFileConsentAcceptAsync	当用户接受文件同意卡时，将调用此方法。
fileConsent/invoke	OnTeamsFileConsentAsync	当连接器收到文件同意卡活动时，将调用此方法。
fileConsent/invoke	OnTeamsFileConsentDeclineAsync	当用户拒绝文件同意卡时，将调用此方法。
actionableMessage/executeAction	OnTeamsO365ConnectorCardActionAsync	当连接器收到Microsoft 365 组操作活动的连接器卡时，将调用此方法。
signin/verifyState	OnTeamsSigninVerifyStateAsync	当连接器收到 signIn 验证状态活动时，将调用此方法。
task/fetch	OnTeamsTaskModuleFetchAsync	可以在派生类中重写此方法，以在提取 TeamsJS v1.x) 中称为任务模块的对话 (提供逻辑。
task/submit	OnTeamsTaskModuleSubmitAsync	可以在派生类中重写此方法，以在提交对话时提供逻辑。

本部分中列出的“调用”活动适用于 Teams 中的对话机器人。 Bot Framework SDK 还支持调用特定于消息扩展的活动。 有关详细信息，请参阅什么是消息扩展。

JavaScript

核心 Bot Framework 处理程序

注意

除已添加和已删除成员的活动外，本部分中介绍的所有活动处理程序继续与非 Teams 机器人一样运行。

活动处理程序在团队的上下文中有所不同，其中新成员将添加到团队而不是消息线程。

中 ActivityHandler 定义的处理程序列表包括以下事件：

Event	处理程序	说明
收到的任何活动类型	onTurn	此方法根据收到的活动类型调用其他处理程序之一。
收到的消息活动	onMessage	此方法有助于处理 Message 活动。
收到的消息更新活动	onMessageUpdate	如果更新消息，此方法将调用处理程序。
收到的邮件删除活动	onMessageDelete	如果删除消息，此方法将调用处理程序。
收到的对话更新活动	onConversationUpdate	如果机器人以外的成员已加入或离开对话，则此方法在活动上 ConversationUpdate 调用处理程序。
非机器人成员加入了对话	onMembersAdded	此方法有助于处理加入会话的成员。
非机器人成员离开了对话	onMembersRemoved	此方法有助于处理离开会话的成员。
收到的事件活动	onEvent	此方法在 Event 活动上调用特定于事件类型的处理程序。
收到的令牌响应事件活动	onTokenResponseEvent	此方法有助于处理令牌响应事件。
收到的其他活动类型	onUnrecognizedActivityType	此方法有助于处理任何未处理的活动类型。
邮件编辑	onTeamsMessageEditEvent	可以重写此方法，以在编辑对话中的消息时进行处理。
message undelete	onTeamsMessageUndeleteEvent	可以重写此方法，以处理取消删除会话中已删除的邮件。 例如，当用户决定撤消已删除的邮件时。
邮件软删除	onTeamsMessageSoftDeleteEvent	可以重写此方法，以在对话中的邮件被软删除时进行处理。

Teams 特定的活动处理程序

扩展 TeamsActivityHandler 核心 Bot Framework 处理程序节中的处理程序列表，以包括以下事件：

Event	处理程序	说明
channelCreated	onTeamsChannelCreated	可以重写此方法来处理正在创建的 Teams 频道。 有关详细信息，请参阅在对话更新事件中创建的通道。
ChannelDeleted	onTeamsChannelDeleted	可以重写此方法来处理要删除的 Teams 频道。 有关详细信息，请参阅对话更新事件中已删除的通道。
channelRenamed	onTeamsChannelRenamed	可以重写此方法以处理要重命名的 Teams 频道。 有关详细信息，请参阅对话更新事件中重命名的通道。
teamRenamed	onTeamsTeamRenamed	return Task.CompletedTask; 可以重写此方法来处理要重命名的 Teams 团队。 有关详细信息，请参阅在对话更新事件中重命名的团队。
MembersAdded	onTeamsMembersAdded	此方法调用 ActivityHandler 中的 OnMembersAddedAsync 方法。 可以重写此方法来处理加入团队的成员。 有关详细信息，请参阅对话更新事件中添加的团队成员。
MembersRemoved	onTeamsMembersRemoved	此方法调用 ActivityHandler 中的 OnMembersRemovedAsync 方法。 可以重写该方法来处理离开团队的成员。 有关详细信息，请参阅对话更新事件中删除的团队成员。

Teams 调用活动

下表提供了从 Teams 活动处理程序调用的 onInvokeActivity Teams 活动处理程序的列表：

调用类型	处理程序	说明
CardAction.Invoke	handleTeamsCardActionInvoke	从连接器接收到卡操作调用活动时，将调用此方法。
fileConsent/invoke	handleTeamsFileConsentAccept	当用户接受文件同意卡时，将调用此方法。
fileConsent/invoke	handleTeamsFileConsent	从连接器接收文件同意卡活动时，将调用此方法。
fileConsent/invoke	handleTeamsFileConsentDecline	当用户拒绝文件同意卡时，将调用此方法。
actionableMessage/executeAction	handleTeamsO365ConnectorCardAction	当从连接器接收Microsoft 365 组操作活动的连接器卡时，将调用此方法。
signin/verifyState	handleTeamsSigninVerifyState	当从连接器接收验证状态活动时 signIn ，将调用此方法。
task/fetch	handleTeamsTaskModuleFetch	此方法可以在派生类中重写，以在提取对话时提供逻辑。
task/submit	handleTeamsTaskModuleSubmit	可以在派生类中重写此方法，以在提交对话时提供逻辑。

本部分中列出的调用活动适用于 Teams 中的聊天机器人。 Bot Framework SDK 还支持调用特定于消息扩展的活动。 有关详细信息，请参阅什么是消息扩展。

Python

核心 Bot Framework 处理程序

注意

除已添加和已删除成员的活动外，本部分中介绍的所有活动处理程序继续与非 Teams 机器人一样运行。

活动处理程序在团队的上下文中有所不同，其中新成员将添加到团队而不是消息线程。

中 ActivityHandler 定义的处理程序列表包括以下事件：

Event	处理程序	说明
收到的任何活动类型	on_turn	此方法根据收到的活动类型调用其他处理程序之一。
收到的消息活动	on_message_activity	可以重写此方法来处理 Message 活动。
收到的对话更新活动	on_conversation_update_activity	如果机器人以外的成员加入或离开会话，此方法将调用处理程序。
非机器人成员加入了对话	on_members_added_activity	可以重写此方法来处理加入会话的成员。
非机器人成员离开了对话	on_members_removed_activity	可以重写此方法来处理离开会话的成员。
收到的事件活动	on_event_activity	此方法调用特定于事件类型的处理程序。
收到的令牌响应事件活动	on_token_response_event	可以重写此方法来处理令牌响应事件。
收到的非令牌响应事件活动	on_event	可以重写此方法来处理其他类型的事件。
收到的其他活动类型	on_unrecognized_activity_type	可以重写此方法以处理未处理的任何类型的活动。

Teams 特定的活动处理程序

扩展 TeamsActivityHandler 了核心 Bot Framework 处理程序部分的处理程序列表，以包括以下事件：

Event	处理程序	说明
channelCreated	on_teams_channel_created	可以重写此方法来处理正在创建的 Teams 频道。 有关详细信息，请参阅在对话更新事件中创建的通道。
ChannelDeleted	on_teams_channel_deleted	可以重写此方法来处理要删除的 Teams 频道。 有关详细信息，请参阅对话更新事件中已删除的通道。
channelRenamed	on_teams_channel_renamed	可以重写此方法以处理要重命名的 Teams 频道。 有关详细信息，请参阅对话更新事件中重命名的通道。
teamRenamed	on_teams_team_renamed	可以重写此方法来处理要重命名的 Teams 团队。 有关详细信息，请参阅在对话更新事件中重命名的团队。
MembersAdded	on_teams_members_added	此方法调用 ActivityHandler 中的 OnMembersAddedAsync 方法。 可以重写此方法来处理加入团队的成员。 有关详细信息，请参阅对话更新事件中添加的团队成员。
MembersRemoved	on_teams_members_removed	此方法调用 ActivityHandler 中的 OnMembersRemovedAsync 方法。 可以重写该方法来处理离开团队的成员。 有关详细信息，请参阅对话更新事件中删除的团队成员。

Teams 调用活动

从 Teams 活动处理程序调用的 on_invoke_activity Teams 活动处理程序列表包括以下调用类型：

调用类型	处理程序	说明
CardAction.Invoke	on_teams_card_action_invoke	从连接器接收到卡操作调用活动时，将调用此方法。
fileConsent/invoke	on_teams_file_consent_accept	当用户接受文件同意卡时，将调用此方法。
fileConsent/invoke	on_teams_file_consent	从连接器接收文件同意卡活动时，将调用此方法。
fileConsent/invoke	on_teams_file_consent_decline	当用户拒绝文件同意卡时，将调用此方法。
actionableMessage/executeAction	on_teams_o365_connector_card_action	当从连接器接收Microsoft 365 组操作活动的连接器卡时，将调用此方法。
signin/verifyState	on_teams_signin_verify_state	当从连接器接收验证状态活动时 signIn ，将调用此方法。
task/fetch	on_teams_task_module_fetch	此方法可以在派生类中重写，以在提取对话时提供逻辑。
task/submit	on_teams_task_module_submit	可以在派生类中重写此方法，以在提交对话时提供逻辑。

本部分中列出的调用活动适用于 Teams 中的聊天机器人。 Bot Framework SDK 还支持调用特定于消息扩展的活动。 有关详细信息，请参阅什么是消息扩展。

---

现在，你已熟悉机器人活动处理程序，让我们看看机器人如何根据聊天以及它接收或发送的消息以不同的方式行为。

代码示例

示例名称	Description	.NET	Node.js	Python
Teams 对话自动程序	此示例应用演示如何使用 Bot Framework v4 中提供的不同机器人聊天事件。	View	View	View
机器人示例	Bot Framework v4 示例集。	View	View	View

后续步骤

对话基础知识

另请参阅

• 为 Teams 生成机器人
• 团队 JavaScript 客户端 SDK
• Teams 的应用清单架构
• Bot Framework 连接器服务的 API 参考
• 获取机器人的 Teams 特定上下文
• 智能机器人对话中的邮件
• 组件和瀑布对话