你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Microsoft Teams 机器人的工作原理

适用于：SDK v4

本文基于机器人工作原理和事件驱动对话中学到的内容；在继续之前，应熟悉这些文章。

Microsoft Teams 上开发的机器人的主要的不同是处理活动的方式。 “Teams 活动处理程序”派生自“活动处理程序”，并在处理更多常规活动类型之前处理特定于 Teams 的活动类型。

注意

Bot Framework JavaScript、C# 和 Python SDK 将继续受支持，但 Java SDK 即将停用，最终长期支持将于 2023 年 11 月结束。

使用 Java SDK 构建的现有机器人将继续正常运行。

对于新的机器人生成，请考虑使用 Power Virtual Agents 并参阅选择合适的聊天机器人解决方案。

有关详细信息，请参阅机器人构建的未来。

Teams 活动处理程序

若要为 Teams 创建机器人，请从 “Teams 活动处理程序”类派生机器人。 当此类机器人收到活动时，它会通过各种“活动处理程序”路由活动。 初始基处理程序是“轮次处理程序”，它根据活动的类型将活动路由到处理程序。 “轮次处理程序”调用旨在处理接收的特定类型活动的处理程序。 “Teams 活动处理程序”类派生自“活动处理程序”类。 除了“活动处理程序”可以处理的活动类型外，Teams 活动处理程序类还包括 Teams 特定活动的其他处理程序。

从 Teams 活动处理程序派生的机器人类似于直接从活动处理程序类派生的机器人。 但是，Teams 在 conversationUpdate 活动中包含其他信息，并发送特定于 Teams 的 invoke 活动和 event 活动。

C#

当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 OnMessageActivityAsync 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 OnConversationUpdateActivityAsync 处理程序将处理该活动。

在这些特定于 Teams 的活动处理程序中，大多数没有基实现。 需要替代这些处理程序并为机器人提供适当的逻辑。

JavaScript

当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 onMessage 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 dispatchConversationUpdateActivity 处理程序将处理该活动。

在这些特定于 Teams 的活动处理程序中，大多数没有基实现。 需要替代这些处理程序并为机器人提供适当的逻辑。

在替代这些特定于 Teams 的活动处理程序时，请定义机器人逻辑，并“务必在最后调用 next()”。 调用 next() 可确保运行下一个处理程序。

Java

当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 onMessageActivity 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 onConversationUpdateActivity 处理程序将处理该活动。

在这些特定于 Teams 的活动处理程序中，大多数没有基实现。 需要替代这些处理程序并为机器人提供适当的逻辑。

Python

当 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 对话更新事件一文介绍了如何使用每个事件。

C#

下面列出了从 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	当机器人安装团队未存档时发送。	团队未存档。

JavaScript

开发人员可以通过两种方法处理从 Microsoft Teams 发送的对话更新活动：

1. 若要传入回调，请使用以 on 开头“且”以 Event 结尾的方法（例如，onTeamsMembersAddedEvent 方法）。
2. 创建派生类时，重写以 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	当机器人安装团队未存档时发送。	团队未存档。

Java

下面列出了从 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	当机器人安装团队未存档时发送。	团队未存档。

Python

下面列出了从 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 中的对话机器人。

C#

这些是从 OnEventActivityAsyncTeams 活动处理程序调用的特定于 Teams 的事件活动处理程序。

事件类型	Handler	说明
application/vnd.microsoft.meetingEnd	OnTeamsMeetingEndAsync	机器人与刚刚结束的会议相关联。
application/vnd.microsoft.meetingStart	OnTeamsMeetingStartAsync	机器人与刚刚启动的会议相关联。

JavaScript

这些是从 onEventActivityTeams 活动处理程序调用的特定于 Teams 的事件活动处理程序。

事件类型	Handler	说明
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	机器人与刚刚结束的会议相关联。
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	机器人与刚刚启动的会议相关联。

Java

这些是从 onEventActivityTeams 活动处理程序调用的特定于 Teams 的事件活动处理程序。

事件类型	Handler	说明
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	机器人与刚刚结束的会议相关联。
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	机器人与刚刚启动的会议相关联。

Python

这些是从 on_event_activityTeams 活动处理程序调用的特定于 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) 将任务模块称为模式“对话”。 有关详细信息，请参阅对话。

C#

下面列出了从 OnInvokeActivityAsyncTeams 活动处理程序调用的所有 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 任务模块提交。

JavaScript

下面列出了从 onInvokeActivityTeams 活动处理程序调用的所有 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 任务模块（模式对话）提交。

Java

下面列出了从 onInvokeActivityTeams 活动处理程序调用的所有 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 登录验证状态。

Python

下面列出了从 on_invoke_activityTeams 活动处理程序调用的所有 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 开发人员文档。