Microsoft Teams 机器人的工作原理
适用于：SDK v4
本文基于机器人工作原理和事件驱动对话中学到的内容；在继续之前，应熟悉这些文章。
Microsoft Teams 上开发的机器人的主要的不同是处理活动的方式。 “Teams 活动处理程序”派生自“活动处理程序”，并在处理更多常规活动类型之前处理特定于 Teams 的活动类型。
Teams 活动处理程序
若要为 Teams 创建机器人，请从 “Teams 活动处理程序”类派生机器人。 当此类机器人收到活动时，它会通过各种“活动处理程序”路由活动。 初始基处理程序是“轮次处理程序”，它根据活动的类型将活动路由到处理程序。 “轮次处理程序”调用旨在处理接收的特定类型活动的处理程序。 “Teams 活动处理程序”类派生自“活动处理程序”类。 除了“活动处理程序”可以处理的活动类型外，Teams 活动处理程序类还包括 Teams 特定活动的其他处理程序。
从 Teams 活动处理程序派生的机器人类似于直接从活动处理程序类派生的机器人。
但是，Teams 在 conversationUpdate 活动中包含其他信息，并发送特定于 Teams 的 invoke 活动和 event 活动。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 OnMessageActivityAsync 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 OnConversationUpdateActivityAsync 处理程序将处理该活动。
在这些特定于 Teams 的活动处理程序中，大多数没有基实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 onMessage 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 dispatchConversationUpdateActivity 处理程序将处理该活动。
在这些特定于 Teams 的活动处理程序中，大多数没有基实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
在替代这些特定于 Teams 的活动处理程序时，请定义机器人逻辑，并“务必在最后调用 next()”。 调用 next() 可确保运行下一个处理程序。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 onMessageActivity 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 onConversationUpdateActivity 处理程序将处理该活动。
在这些特定于 Teams 的活动处理程序中，大多数没有基实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 on_message_activity 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 on_conversation_update_activity 处理程序将处理该活动。
在这些特定于 Teams 的活动处理程序中，大多数没有基实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
“使用活动处理程序的事件驱动聊天”一文的活动处理部分所述的所有活动处理程序会像在非 Teams 机器人中一样继续工作，不过，成员添加和删除活动在团队的上下文中不同，其中的新成员将添加到团队，而不是添加到消息线程。 有关详细信息，请参阅 Teams 对话更新活动。
若要为这些特定于 Teams 的活动处理程序实现逻辑，需要替代机器人中的方法。
Teams 机器人逻辑
机器人逻辑处理来自一个或多个机器人通道的传入活动，并在响应中生成传出活动。 对于派生自 Teams 活动处理程序类的机器人也仍是如此，该处理程序首先检查 Teams 活动，然后将所有其他活动传递给 Bot Framework 的活动处理程序。
Teams 安装更新活动
为“安装更新”事件添加处理程序，让机器人：
- 在对话线程上安装时发送介绍性消息。
- 从线程卸载时清理用户和线程数据。
有关详细信息，请参阅 Teams 文档中的安装更新事件。
Teams 聊天更新活动
下表列出了在机器人中生成“对话更新”活动的 Teams 事件。
Microsoft Teams 对话更新事件一文介绍了如何使用每个事件。
下面列出了从 Teams 活动处理程序的 OnConversationUpdateActivityAsync 方法调用的所有 Teams 活动处理程序。
| EventType |
处理程序 |
条件 |
Teams 文档 |
| channelCreated |
OnTeamsChannelCreatedAsync |
每当安装了机器人的团队中创建新通道时就会发送。 |
创建通道。 |
| channelDeleted |
OnTeamsChannelDeletedAsync |
每当在机器人安装团队中删除通道时发送。 |
删除通道。 |
| channelRenamed |
OnTeamsChannelRenamedAsync |
每当在机器人安装团队中重命名通道时发送。 |
已重命名通道。 |
| channelRestored |
OnTeamsChannelRestoredAsync |
每当在机器人安装团队中还原先前删除的的通道时发送。 |
通道已还原。 |
| membersAdded |
OnTeamsMembersAddedAsync |
默认情况下，调用 ActivityHandler.OnMembersAddedAsync 方法。 首次将机器人添加到对话时，以及每次将新用户添加到机器人安装到的团队或群聊中时发送。 |
已添加团队成员。 |
| membersRemoved |
OnTeamsMembersRemovedAsync |
默认情况下，调用 ActivityHandler.OnMembersRemovedAsync 方法。 如果机器人从团队中删除，以及每当从机器人所属的团队中删除任何用户时，都会发送。 |
已删除团队成员。 |
| teamArchived |
OnTeamsTeamArchivedAsync |
当安装了机器人的团队已存档时会发送。 |
团队已存档。 |
| teamDeleted |
OnTeamsTeamDeletedAsync |
当安装了机器人的团队被删除时会发送。 |
团队已删除。 |
| teamRenamed |
OnTeamsTeamRenamedAsync |
重命名机器人的团队时发送。 |
团队已重命名。 |
| teamRestored |
OnTeamsTeamRestoredAsync |
还原之前删除的机器人团队时发送。 |
团队已还原。 |
| teamUnarchived |
OnTeamsTeamUnarchivedAsync |
当机器人安装团队未存档时发送。 |
团队未存档。 |
开发人员可以通过两种方法处理从 Microsoft Teams 发送的对话更新活动：
- 若要传入回调，请使用以
on 开头并以 Event 结尾的方法（例如 onTeamsMembersAddedEvent 方法）。
- 创建派生类时，重写以
on 开头且“不”以 Event 结尾的方法（例如，onTeamsMembersAdded 方法）。
开发人员应仅使用以下选项之一：1 或 2，而不是“同时用于”同一活动。 这意味着，开发人员应将回调传递给 onTeamsMembersAddedEvent 方法“或”重写派生类中的 onTeamsMembersAdded 方法，并且不同时执行这两项操作。
注册回调的方法
下面列出了从 Teams 活动处理程序的 dispatchConversationUpdateActivity 方法调用的所有 Teams 活动发射器。
| EventType |
注册方法 |
条件 |
Teams 文档 |
| channelCreated |
onTeamsChannelCreatedEvent |
每当安装了机器人的团队中创建新通道时就会发送。 |
创建通道。 |
| channelDeleted |
onTeamsChannelDeletedEvent |
每当在机器人安装团队中删除通道时发送。 |
删除通道。 |
| channelRenamed |
onTeamsChannelRenamedEvent |
每当在机器人安装团队中重命名通道时发送。 |
已重命名通道。 |
| channelRestored |
onTeamsChannelRestoredEvent |
每当在机器人安装团队中还原先前删除的的通道时发送。 |
通道已还原。 |
| membersAdded |
onTeamsMembersAddedEvent |
首次将机器人添加到对话时，以及每次将新用户添加到机器人安装到的团队或群聊中时发送。 |
已添加团队成员。 |
| membersRemoved |
onTeamsMembersRemovedEvent |
如果机器人从团队中删除，以及每当从机器人所属的团队中删除任何用户时，都会发送。 |
已删除团队成员。 |
| teamArchived |
onTeamsTeamArchivedEvent |
当安装了机器人的团队已存档时会发送。 |
团队已存档。 |
| teamDeleted |
onTeamsTeamDeletedEvent |
当安装了机器人的团队被删除时会发送。 |
团队已删除。 |
| teamRenamed |
onTeamsTeamRenamedEvent |
重命名机器人的团队时发送。 |
团队已重命名。 |
| teamRestored |
onTeamsTeamrestoredEvent |
还原之前删除的机器人团队时发送。 |
团队已还原。 |
| teamUnarchived |
onTeamsTeamUnarchivedEvent |
当机器人安装团队未存档时发送。 |
团队未存档。 |
在派生类中替代的方法
下面列出了可以重载的所有 Teams 活动处理程序，以处理 Teams 对话更新活动。
| EventType |
处理程序 |
条件 |
Teams 文档 |
| channelCreated |
onTeamsChannelCreated |
每当安装了机器人的团队中创建新通道时就会发送。 |
创建通道。 |
| channelDeleted |
onTeamsChannelDeleted |
每当在机器人安装团队中删除通道时发送。 |
删除通道。 |
| channelRenamed |
onTeamsChannelRenamed |
每当在机器人安装团队中重命名通道时发送。 |
已重命名通道。 |
| channelRestored |
onTeamsChannelRestored |
每当在机器人安装团队中还原先前删除的的通道时发送。 |
通道已还原。 |
| membersAdded |
onTeamsMembersAdded |
默认情况下，调用 ActivityHandler.onMembersAdded 方法。 首次将机器人添加到对话时，以及每次将新用户添加到机器人安装到的团队或群聊中时发送。 |
已添加团队成员。 |
| membersRemoved |
onTeamsMembersRemoved |
默认情况下，调用 ActivityHandler.onMembersRemoved 方法。 如果机器人从团队中删除，以及每当从机器人所属的团队中删除任何用户时，都会发送。 |
已删除团队成员。 |
| teamArchived |
onTeamsTeamArchived |
当安装了机器人的团队已存档时会发送。 |
团队已存档。 |
| teamDeleted |
onTeamsTeamDeleted |
当安装了机器人的团队被删除时会发送。 |
团队已删除。 |
| teamRenamed |
onTeamsTeamRenamed |
重命名机器人的团队时发送。 |
团队已重命名。 |
| teamRestored |
onTeamsTeamRestored |
还原之前删除的机器人团队时发送。 |
团队已还原。 |
| teamUnarchived |
onTeamsTeamUnarchived |
当机器人安装团队未存档时发送。 |
团队未存档。 |
下面列出了从 Teams 活动处理程序的 onConversationUpdateActivity 方法调用的所有 Teams 活动处理程序。
| EventType |
处理程序 |
条件 |
Teams 文档 |
| channelCreated |
onTeamsChannelCreated |
每当安装了机器人的团队中创建新通道时就会发送。 |
创建通道。 |
| channelDeleted |
onTeamsChannelDeleted |
每当在机器人安装团队中删除通道时发送。 |
删除通道。 |
| channelRenamed |
onTeamsChannelRenamed |
每当在机器人安装团队中重命名通道时发送。 |
已重命名通道。 |
| channelRestored |
onTeamsChannelRestored |
每当在机器人安装团队中还原先前删除的的通道时发送。 |
通道已还原。 |
| membersAdded |
onTeamsMembersAdded |
默认情况下，调用 ActivityHandler.onMembersAdded 方法。 首次将机器人添加到对话时，以及每次将新用户添加到机器人安装到的团队或群聊中时发送。 |
已添加团队成员。 |
| membersRemoved |
onTeamsMembersRemoved |
默认情况下，调用 ActivityHandler.onMembersRemoved 方法。 如果机器人从团队中删除，以及每当从机器人所属的团队中删除任何用户时，都会发送。 |
已删除团队成员。 |
| teamArchived |
onTeamsTeamArchived |
当安装了机器人的团队已存档时会发送。 |
团队已存档。 |
| teamDeleted |
onTeamsTeamDeleted |
当安装了机器人的团队被删除时会发送。 |
团队已删除。 |
| teamRenamed |
onTeamsTeamRenamed |
重命名机器人的团队时发送。 |
团队已重命名。 |
| teamRestored |
onTeamsTeamRestored |
还原之前删除的机器人团队时发送。 |
团队已还原。 |
| teamUnarchived |
onTeamsTeamUnarchived |
当机器人安装团队未存档时发送。 |
团队未存档。 |
下面列出了从 Teams 活动处理程序的 on_conversation_update_activity 方法调用的所有 Teams 活动处理程序。
| EventType |
处理程序 |
条件 |
Teams 文档 |
| channelCreated |
on_teams_channel_created |
每当安装了机器人的团队中创建新通道时就会发送。 |
创建通道。 |
| channelDeleted |
on_teams_channel_deleted |
每当在机器人安装团队中删除通道时发送。 |
删除通道。 |
| channelRenamed |
on_teams_channel_renamed |
每当在机器人安装团队中重命名通道时发送。 |
已重命名通道。 |
| channelRestored |
on_teams_channel_restored |
每当在机器人安装团队中还原先前删除的的通道时发送。 |
通道已还原。 |
| membersAdded |
on_teams_members_added |
默认情况下，调用基类 on_members_added_activity 方法。 首次将机器人添加到对话时，以及每次将新用户添加到机器人安装到的团队或群聊中时发送。 |
已添加团队成员。 |
| membersRemoved |
on_teams_members_removed |
默认情况下，调用基类 on_members_removed_activity 方法。 如果机器人从团队中删除，以及每当从机器人所属的团队中删除任何用户时，都会发送。 |
已删除团队成员。 |
| teamArchived |
on_teams_team_archived |
当安装了机器人的团队已存档时会发送。 |
团队已存档。 |
| teamDeleted |
on_teams_team_deleted |
当安装了机器人的团队被删除时会发送。 |
团队已删除。 |
| teamRenamed |
on_teams_team_renamed |
重命名机器人的团队时发送。 |
团队已重命名。 |
| teamRestored |
on_teams_team_restored |
还原之前删除的机器人团队时发送。 |
团队已还原。 |
| teamUnarchived |
on_teams_team_unarchived |
当机器人安装团队未存档时发送。 |
团队未存档。 |
Teams 事件活动
下表列出了 Teams 发送到机器人的特定于 Teams 的事件活动。
列出的事件活动适用于 Teams 中的对话机器人。
这些是从 Teams 活动处理程序调用的特定于 OnEventActivityAsync Teams 的事件活动处理程序。
| 事件类型 |
Handler |
说明 |
| application/vnd.microsoft.meetingEnd |
OnTeamsMeetingEndAsync |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
OnTeamsMeetingStartAsync |
机器人与刚刚启动的会议相关联。 |
这些是从 Teams 活动处理程序调用的特定于 onEventActivity Teams 的事件活动处理程序。
| 事件类型 |
Handler |
说明 |
| application/vnd.microsoft.meetingEnd |
onTeamsMeetingEnd |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
onTeamsMeetingStart |
机器人与刚刚启动的会议相关联。 |
这些是从 Teams 活动处理程序调用的特定于 onEventActivity Teams 的事件活动处理程序。
| 事件类型 |
Handler |
说明 |
| application/vnd.microsoft.meetingEnd |
onTeamsMeetingEnd |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
onTeamsMeetingStart |
机器人与刚刚启动的会议相关联。 |
这些是从 Teams 活动处理程序调用的特定于 on_event_activity Teams 的事件活动处理程序。
| 事件类型 |
Handler |
说明 |
| application/vnd.microsoft.meetingEnd |
on_teams_meeting_end_event |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
on_teams_meeting_start_event |
机器人与刚刚启动的会议相关联。 |
Teams 调用活动
下表列出了 Teams 发送到机器人的特定于 Teams 的调用活动。
列出的调用活动适用于 Teams 中的对话机器人。 Bot Framework SDK 还支持特定于消息传送扩展的调用。 有关详细信息，请参阅 Teams 什么是消息传递扩展一文。
注意
Microsoft Teams 平台文档和 Teams JavaScript 客户端库 (TeamsJS) 将任务模块称为模式“对话”。 有关详细信息，请参阅对话。
下面列出了从 Teams 活动处理程序调用的所有 OnInvokeActivityAsync Teams 活动处理程序：
| 调用类型 |
Handler |
说明 |
| actionableMessage/executeAction |
OnTeamsO365ConnectorCardActionAsync |
Teams O365 连接器卡片操作。 |
| CardAction.Invoke |
OnTeamsCardActionInvokeAsync |
Teams 卡片操作调用。 |
| fileConsent/invoke |
OnTeamsFileConsentAcceptAsync |
Teams 文件许可接受。 |
| fileConsent/invoke |
OnTeamsFileConsentAsync |
Teams 文件许可。 |
| fileConsent/invoke |
OnTeamsFileConsentDeclineAsync |
Teams 文件许可。 |
| signin/verifyState |
OnTeamsSigninVerifyStateAsync |
Teams 登录验证状态。 |
| task/fetch |
OnTeamsTaskModuleFetchAsync |
Teams 任务模块提取。 |
| task/submit |
OnTeamsTaskModuleSubmitAsync |
Teams 任务模块提交。 |
下面列出了从 Teams 活动处理程序调用的所有 onInvokeActivity Teams 活动处理程序：
| 调用类型 |
Handler |
说明 |
| actionableMessage/executeAction |
handleTeamsO365ConnectorCardAction |
Teams O365 连接器卡片操作。 |
| CardAction.Invoke |
handleTeamsCardActionInvoke |
Teams 卡片操作调用。 |
| fileConsent/invoke |
handleTeamsFileConsentAccept |
Teams 文件许可接受。 |
| fileConsent/invoke |
handleTeamsFileConsent |
Teams 文件许可。 |
| fileConsent/invoke |
handleTeamsFileConsentDecline |
Teams 文件许可。 |
| signin/verifyState |
handleTeamsSigninVerifyState |
Teams 登录验证状态。 |
| task/fetch |
handleTeamsTaskModuleFetch |
Teams 任务模块（模式对话）提取。 |
| task/submit |
handleTeamsTaskModuleSubmit |
Teams 任务模块（模式对话）提交。 |
下面列出了从 Teams 活动处理程序调用的所有 onInvokeActivity Teams 活动处理程序：
| 调用类型 |
Handler |
说明 |
| fileConsent/invoke |
onTeamsFileConsent |
Teams 文件许可。 |
| actionableMessage/executeAction |
onTeamsO365ConnectorCardAction |
Teams O365 连接器卡片操作。 |
| task/fetch |
onTeamsTaskModuleFetch |
Teams 任务模块提取。 |
| task/submit |
onTeamsTaskModuleSubmit |
Teams 任务模块提交。 |
| tab/fetch |
onTeamsTabFetch |
Teams 选项卡提取。 |
| tab/submit |
onTeamsTabSubmit |
Teams 选项卡提交。 |
| CardAction.Invoke |
onTeamsCardActionInvoke |
Teams 卡片操作调用。 |
| fileConsent/invoke |
onTeamsFileConsentAccept |
Teams 文件许可接受。 |
| fileConsent/invoke |
onTeamsFileConsentDecline |
Teams 文件许可。 |
| signin/verifyState |
onTeamsSigninVerifyState |
Teams 登录验证状态。 |
下面列出了从 Teams 活动处理程序调用的所有 on_invoke_activity Teams 活动处理程序：
| 调用类型 |
Handler |
说明 |
| actionableMessage/executeAction |
on_teams_o365_connector_card_action |
Teams O365 连接器卡片操作。 |
| CardAction.Invoke |
on_teams_card_action_invoke |
Teams 卡片操作调用。 |
| fileConsent/invoke |
on_teams_file_consent_accept |
Teams 文件许可接受。 |
| fileConsent/invoke |
on_teams_file_consent |
Teams 文件许可。 |
| fileConsent/invoke |
on_teams_file_consent_decline |
Teams 文件许可拒绝。 |
| signin/verifyState |
on_teams_signin_verify_state |
Teams 登录验证状态。 |
| task/fetch |
on_teams_task_module_fetch |
Teams 任务模块提取。 |
| task/submit |
on_teams_task_module_submit |
Teams 任务模块提交。 |
后续步骤
有关构建 Teams 机器人的信息，请参阅 Microsoft Teams 开发人员文档。