【Microsoft Bot】Microsoft Bot Framework--活动

摘要

Bot框架活动模式是由人类和自动化软件进行的会话操作的应用程序级表示。该模式包括用于交流文本、多媒体和非内容动作（如社交互动和打字指示器）的规定。

该模式在Bot框架协议中使用，并由Microsoft聊天系统以及可互操作的机器人和来自许多来源的客户端实现。

1. Introduction
2. Basic activity structure
3. Message activity
4. Contact relation update activity
5. Conversation update activity
6. End of conversation activity
7. Event activity
8. Invoke activity
9. Installation update activity
10. Message delete activity
11. Message update activity
12. Message reaction activity
13. Suggestion activity
14. Trace activity
15. Typing activity
16. Handoff activity
17. Command activity
18. Command result activity
19. Complex types
20. References
21. Appendix I - Changes
22. Appendix II - Non-IRI entity types
23. Appendix III - Protocols using the Invoke activity
24. Appendix IV - Priming format
25. Appendix V - Caller ID values
26. Appendix VI - Protocols using the Command activity
     

介绍

概述

Bot框架活动模式表示聊天应用程序、电子邮件和其他文本交互程序中人类和自动化软件的对话行为。每个活动对象都包括一个类型字段，并表示一个动作：最常见的是发送文本内容，但也包括多媒体附件和非内容行为，如“点赞”按钮或打字指示器。

本文档提供了每种活动类型的含义，并描述了可能包含的必填字段和可选字段。它还定义了客户端和服务器的角色，并提供了每个参与者掌握哪些字段以及哪些字段可以忽略的指导。

该规范中有三个重要角色：客户端，代表用户发送和接收活动；机器人，发送和接收活动，通常是自动化的；以及在客户端和机器人之间存储和转发活动的通道。

尽管本规范要求在角色之间传输活动，但此处未描述传输的确切性质。这可以在配套的Bot框架协议规范[1]中找到。

为了紧凑起见，本规范中未定义视觉交互卡。相反，这些是在Bot框架卡[10]和自适应卡[11]规范中定义的。这些卡和其他未定义的卡类型可以作为附件包含在Bot Framework活动中。

要求

本文件中的关键词“必须”、“不得”、“要求”、“应”、“不应”、”应“、”不应“、“推荐”、“可能”和“可选”应按照RFC 2119[2]中的描述进行解释。

如果一个实现未能满足其实现的协议的一个或多个MUST或REQUIRED级别要求，则该实现不符合要求。满足其协议的所有MUST或REQUIRED级别和所有SHOULD级别要求的实现被称为“无条件符合”；一个满足其协议的所有MUST级别要求但不是所有SHOULD级别要求的协议被称为“有条件兼容”

解释性文本描述了意图。鼓励编辑在解释文本中省略规范性说明。所有编号的要求都是规范性的。所有的例子都是不规范的。

编号的需求

以AXXXX形式的标记开头的行是特定的要求，设计用于在本文档之外的讨论中通过数字引用。它们不比AXXXX行外的规范性声明具有更多或更少的分量。

A1000：本规范的编辑可能会添加新的AXXXX要求。他们应该找到保留文档流的数字AXXXX值。

A1001:编辑不得重新编号现有的AXXXX要求。

A1002：编辑可删除或修订AXXXX要求。如果修改了，如果需求的主题基本保持不变，编辑器应该保留现有的AXXXX值。

A1003：编辑不应重复使用已失效的AXXXX值。可在本文件末尾保留已删除值的列表。

术语

活动

由机器人程序、通道或客户端表示的符合活动模式的操作。

频道

发送和接收活动，并将其转换为聊天或应用程序行为的软件。通道是活动数据的权威存储。

机器人程序(bot)

发送和接收活动，并生成自动、半自动或完全手动响应的软件。Bot具有已向通道注册的端点。

客户

通常代表人类用户发送和接收活动的软件。客户端没有终结点。

发件人

传输活动的软件。

接受者

接受活动的软件。

端点

机器人程序或通道可以在其中接收活动的可编程寻址位置。

住址

可以联系用户或机器人的标识符或地址。

领域

活动或嵌套对象中的命名值。

总体组织

活动对象是名称/值对的平面列表，其中一些是基元对象，另一些是复杂的（嵌套的）对象。活动对象通常以JSON格式表示，但也可以投影到中的内存中数据结构中。Net或JavaScript。

活动类型字段控制活动的含义及其包含的字段。根据参与者所扮演的角色（客户端、机器人程序或渠道），每个字段都是强制性的、可选的或忽略的。例如，id字段由通道控制，在某些情况下是强制性的，但如果它是由机器人程序发送的，则会被忽略。

描述活动和任何参与者身份的字段（如类型和来自字段）在所有活动中共享。在许多编程语言中，在核心基类型上组织这些字段是很方便的，其他更具体的活动类型就是从核心基类型派生的。

在存储或传输活动时，某些字段可能会在传输机制中重复。例如，如果通过HTTP POST将活动发送到包括会话ID的URL，则接收方可以推断其值，而不要求其存在于活动主体内。本文档仅描述了这些字段的抽象要求，由控制协议确定是否必须显式声明值，或者是否允许隐式或推断值。

当机器人程序或客户端向通道发送活动时，通常是请求记录该活动。当通道向机器人程序或客户端发送活动时，通常会发出活动已被记录的通知。

基本活动结构

本节定义了活动对象的基本结构的要求。

活动对象包括一个称为字段的名称/值对的平面列表。字段可以是基元类型。JSON被用作通用交换格式，尽管并非所有活动都必须始终序列化为JSON，但它们必须可序列化为JSON。这允许实现依赖于一组简单的约定来处理已知和未知的活动字段。

A2001:活动必须可序列化为RFC 4627[15]中定义的JSON格式，包括遵守例如字段唯一性约束。

A2002：接收器可能允许大小写不正确的字段名称，尽管这不是必需的。接收方可能会拒绝不包括具有适当套管的字段的活动。

A2004：除非另有说明，否则发送方不应包含字符串字段的空字符串值。

A2005：除非另有说明，否则发送方可以在活动或任何嵌套的复杂对象中包含其他字段。接收者必须接受他们不理解的字段。

A2006：接收者应该接受他们不理解的类型的事件。

本文档定义“活动”对象中使用的字段的数据类型。这些类型定义包括句法类型（例如字符串或复杂类型），如果是字符串，则包括可选格式（例如ISO 8601日期-时间格式[3]）。

A2007：发件人必须遵守本文档中包含的数据类型定义。

A2003：接收方应拒绝包含类型与本规范中描述的数据类型不匹配的字段值的活动。

类型

类型字段控制每个活动的含义，按照惯例是短字符串（例如“消息”）。发送方可以定义自己的应用层类型，尽管鼓励他们选择不太可能与未来定义良好的值冲突的值。如果发送方使用URI作为类型值，则不应实现URI梯形图比较以建立等效性。

A2010:活动必须包括一个类型字段，其类型为字符串值。

A2011：只有当两个类型值通常相同时，它们才是等效的。

A2012:发送方可能生成本文档中未定义的活动类型值。

A2013:通道应该拒绝它不理解的类型的活动。

A2014：机器人程序或客户端应该忽略它不理解的类型的活动。

通道ID(Channel ID)

channelId字段为活动建立通道和权威存储。channelId字段的值的类型为字符串。

A2020:活动必须包括一个具有字符串值类型的channelId字段。

A2021：只有当两个channelId值通常相同时，它们才是等效的。

A2022：信道可以忽略或拒绝它在没有预期channelId值的情况下接收的任何活动。

ID

一旦活动被记录在通道中，id字段就为其建立标识。飞行中尚未记录的活动没有身份。并非所有活动都被分配了标识（例如，键入活动可能永远不会被分配id。）id字段的值是字符串类型。

A2030：通道应包括一个id字段，如果该字段可用于该活动。

A2031:客户端和机器人不应在其生成的活动中包含id字段。

为了便于实施，应假设其他参与者不具备活动ID的复杂知识，并且他们将仅使用顺序比较来建立等效性。

例如，通道可以为每个活动ID使用十六进制编码的GUID。即使大写编码的GUID在逻辑上等同于小写编码的GUID，发送方也不应在可能的情况下使用这些替代编码。每个ID的规范化版本是由权威存储通道建立的。

A2032：生成id值时，发送方应选择可通过顺序比较建立等效性的值。然而，如果发送者和接收者对环境有特殊的了解，他们可以允许两个不普通等价的值的逻辑等价。

id字段旨在允许重复数据消除，但在大多数应用程序中这是不允许的。

A2033:接收方可以通过ID消除重复活动，但发送方不应依赖接收方执行此消除重复操作。

时间戳

时间戳字段记录活动发生的确切UTC时间。由于计算系统的分布式性质，重要的时间是通道（权威存储）记录活动的时间。客户端或机器人启动活动的时间可以在localTimestamp字段中单独传输。时间戳字段的值是字符串中ISO 8601[3]编码的日期时间。

A2040：如果时间戳字段可用于该活动，则通道应包括该字段。

A2041：客户端和机器人不应在其生成的活动中包含时间戳字段。

A2042：客户端和机器人不应使用时间戳拒绝活动，因为它们可能会出现无序。但是，他们可能会使用时间戳来对UI内的活动进行排序或进行下游处理。

A2043:发送方应始终将时间戳字段的值编码为UTC，并且应始终在值中包含Z作为明确的UTC标记。

当地时区

localTimezone字段表示生成活动的时区。localTimezone字段的值是每个IANA时区数据库的时区名称（区域条目）。[15]

A2055：客户可以在其活动中加入当地时区。

A2056:当将活动从发送者转发到接收者时，频道应保留本地时区。

A2057:接收器可能会忽略它不理解的本地时区值。

本地时间戳

localTimestamp字段表示生成活动的日期时间和时区偏移量。这可能与记录活动的UTC时间戳不同。localTimestamp字段的值是字符串中ISO 8601[3]编码的日期时间。

当localTimezone和localTimestamp字段都包含在活动中时，解释是首先将localTimestaff的值转换为UTC，然后将转换应用于本地时区。

A2050:客户端和机器人可能在其活动中包含localTimestamp字段。它们应该明确列出编码值内的时区偏移量。

A2051:当将活动从发送方转发到接收方时，信道应保留localTimestamp。

From

from字段描述生成活动的客户端、机器人程序或通道。from字段的值是Channel帐户类型的复杂对象。

from.id字段标识生成活动的人员。最常见的情况是，这是系统中的另一个用户或机器人。在某些情况下，from字段标识通道本身。

A2060：生成活动时，通道必须包括from和from.id字段。

A2061:生成活动时，Bot和客户端应包括from和from.id字段。通道可能会因为缺少from和from.id字段而拒绝活动。

from.name字段是可选的，表示频道内帐户的显示名称。通道应该包含此值，以便客户端和机器人程序可以填充其UI和后端系统。Bot和客户端不应将此值发送到具有此存储中心记录的渠道，但他们可能会将该值发送到在每个活动中填充该值的渠道（例如电子邮件渠道）。

A2062：如果存在from字段并且from.name可用，则通道应包括from.name字段。

A2063:Bot和客户端不应包括from.name字段，除非该字段在通道中具有语义价值。

收件人(Recipient)

收件人字段描述哪个客户端或机器人正在接收此活动。只有当一个活动被传递给恰好一个接收者时，此字段才有意义；当它被广播给多个接收者时（当一个活动被发送到一个频道时就会发生这种情况），这是没有意义的。该字段的目的是允许收件人表明自己的身份。当客户端或机器人在通道中具有多个身份时，这很有帮助。收件人字段的值是Channel帐户类型的复杂对象。

A2070：将活动传输到单个收件人时，通道必须包括收件人和收件人.id字段。

A2071:Bot和客户端在生成活动时不应包含收件人字段。例外情况是在发送建议活动时，在这种情况下，收件人必须识别应该接收建议的用户。

receipient.name字段是可选的，表示频道中帐户的显示名称。通道应该包含此值，以便客户端和机器人程序可以填充其UI和后端系统。

A2072：如果存在接收方字段并且接收方名称可用，则通道应包括接收方名称字段。

会话(Conversation)

会话字段描述活动所在的会话。conversation字段的值是conversation帐户类型的复杂对象。

A2080:频道、机器人和客户端在生成活动时必须包括conversation和conversation.id字段。

conversation.name字段是可选的，表示会话的显示名称（如果存在并且可用）。

A2081：频道应包括conversation.name和conversation.isGroup字段（如果可用）。

A2082：Bot和客户端不应包括conversation.name字段，除非该字段在通道中具有语义价值。

A2083:机器人和客户端不应在其生成的活动中包括conversation.isGroup和conversation.coverationType字段。

A2084:如果为通道定义了多个值，则通道应包括conversation.conversationType字段。如果只有一个可能的值，则通道不应包括该字段。

回复ID(Reply to ID)

replyToId字段标识当前活动作为答复的先前活动。此字段允许在参与者之间进行线程对话和评论嵌套。replyToId仅在当前会话中有效。（有关对其他会话的引用，请参阅relatesTo。）replyToId字段的值是一个字符串。

A2090:当某个活动是对另一个活动的答复时，发送方应将replyToId包括在该活动中。

A2091:如果某个通道的replyToId没有引用会话中的有效活动，则该通道可能会拒绝该活动。

A2092：如果Bot和客户端知道通道没有使用该字段，即使发送的活动是对另一个活动的回复，也可以省略replyToId。

实体(Entities)

实体字段包含与此活动相关的元数据对象的平面列表。与附件不同（请参阅附件字段），实体不一定表现为用户可交互的内容元素，如果不被理解，则会被忽略。发送者可以包括他们认为可能对接收者有用的实体，即使他们不确定接收者是否可以接受这些实体。每个实体列表元素的值都是Entity类型的复杂对象。

A2100：如果实体字段不包含任何元素，则发送方应省略该字段。

A2101：发送方可以发送多个相同类型的实体，前提是这些实体具有不同的含义。

A2102：发送方不得包含两个或多个类型和内容相同的实体。

A2103：发送方和接收方不应依赖于活动中包含的实体的特定排序。

A2104：接收方必须忽略其不理解其类型的实体。

A2105：接收方应忽略其理解但由于语法错误等原因无法处理的类型的实体。

通道数据(Channel data)

活动模式中的可扩展性数据主要在channelData字段中组织。这简化了实现协议的SDK中的管道。channelData对象的格式由发送或接收活动的通道定义。

A2200：通道不应定义JSON基元（例如字符串、int）的通道数据格式。相反，他们应该将channelData定义为复杂类型，或者不定义它。

A2201：如果当前信道的channelData格式未定义，接收器应忽略channelData的内容。

主叫号码(Caller ID)

在某些情况下，记录活动的发送位置非常重要。callerId字段是一个包含IRI[4]的字符串，该IRI[4]标识机器人的调用方，在附录V中有更详细的描述。该字段不打算通过有线传输，而是由机器人和客户端基于可加密验证的数据填充，这些数据断言调用方的身份（例如令牌）。

A2250:发送方不应填充callerId字段。

A2251：接收器应丢弃导线上callerId字段中包含的任何数据。

A2252:Bots应该在接收到活动后，用附录V中描述的标识符填充其callerId字段

服务URL

活动通常是异步发送的，具有用于发送和接收流量的独立传输连接。频道使用serviceUrl字段来表示可以发送对当前活动的回复的URL。serviceUrl字段的值的类型为字符串。

A2300：频道必须在发送给机器人的所有活动中包含serviceUrl字段。

A2301：对于那些证明自己已经知道频道端点的客户端，频道不应包括serviceUrl字段。

A2302:机器人和客户端不应在其生成的活动中填充serviceUrl字段。

A2302：频道必须忽略机器人和客户端发送的活动中serviceUrl的值。

A2304:通道应该为serviceUrl字段使用稳定的值，因为机器人程序可能会长时间保存这些值。