Bot Framework 核心概念：参考信息

原文地址：https://docs.botframework.com/en-us/core-concepts/reference/#navtitle

Bot Connector 服务是Bot Framework 的一个组件，它能够让你的机器人很容易地在频道上跟用户进行沟通，比如 SMS，Skype，Slack 和 Facebook，这些频道都是你在注册你的机器人的时候配置好的。Connector 服务存在于你的机器人和频道之间进行着同步消息的工作。

要通过 connector 发送和接收消息，你可以使用 Bot Connector REST API。API 是 endpoints 和 JSON 对象的集合，你用它们来开始对话，发送消息，添加附件和获得对话的成员信息。

查看下边的部分了解什么是 endpoints，headers 和 classes，你会用到他们来编写你的机器人。

Endpoints

下边是你用来发送所有 Connector REST 请求的根 URI。

https://api.botframework.com

下边是你用来访问 Connector resources 的 URI 模板。

模板类型描述资源/v3/conversationPOST用来开始一个 private 或者是小组的对话。详细信息请查看 开始一段对话Request：Conversation
Response：
Identification/v3/conversation/{conversationId}/activitiesPOST用来给对话中的成员发送一条消息。只有当你不是回复从会话中另外一个成员发送过来的消息是使用。详细信息请查看 发送和接收消息Request：
Activity/v3/conversation/{conversationId}/activities/{activityId}POST用来回复会话中的成员发送过来的消息。详细信息请查看 发送和接收消息Request：
Activity/v3/conversation/{conversationId}/membersGET用来获取对话中的成员Response：
ChannelAccount/v3/conversation/{conversationId}/activities/{activityId}/membersGET用来获取一个 Activity 的成员Response：
ChannelAccount/v3/botstate/{channelId}/users/{userId}DELETE用来从 User Data store 和 Private Conversation store 里删除用户状态数据。详细信息请查看 保存用户状态数据 的删除用户状态数据Response：
Identification GET用来从 User Data store 获得用户的状态数据。详细信息请查看 保存用户状态数据 的获得用户数据Response：
UserData POST用来覆盖 User Data store 里的用户状态数据。详细信息请参考 保存用户状态数据 的保存用户数据Request：
UserData
Response：
UserData/v3/botstate/{channelId}/conversations/{conversationId}GET用来获取从 Conversation store 获取的会话的状态数据。详细信息请查看  保存用户状态数据 的获得会话数据Response：
UserData POST用来覆盖 Conversation store 中的会话的状态数据。详细信息请查看 保存用户状态数据 的保存会话数据Request：
UserData
Response：
UserData/v3/botstate/{channelId}/conversations/{conversationId}/users/{userId}GET用来从 Conversation store 中获取用户的状态数据。详细信息请查看 保存用户状态数据 的获得 private 会话数据Response：
UserData POST用来覆盖 Conversation store 中的用户状态数据。详细信息请查看 保存用户状态数据 的保存 private 会话数据Request：
UserData
Response：
UserData

将 {conversationId} 替换成会话的 ID。可以从消息的 conversation 属性中获得 ID，或者如果是你的机器人开始的一段会话，从 response 中可以获得 ID（查看 Identification 对象）。

将 {activityId} 替换成消息的 ID。可以从消息的 id 属性中获得 ID。

将 {channelId} 替换成频道的 ID。可以从消息的 channelId 属性中获得 ID。

将 {userId} 替换成用户的 ID。可以从消息的 from 属性中获得 ID。

Headers

相对于标准的 HTTP request 和 response headers，Connector API 使用下边的 headers。

Header描述Authorization必须的 request header。
包含了用来验证你的机器人的客户端验证 token。详细信息请查看 认证。X-Correlating-OperationIdResponse header。
包含了 log entry 的 ID，其中提供了关于请求的详细信息。如果一个错误发生了的话，你应该总是捕获这个 ID。如果你不能够确认和解决问题的话，将这个 ID 连同其他信息一并提供给 Support team。

Classes

Bot Connector REST API 使用一下的 JSON 对象：

对象描述Activity定义了一个机器人和用户之间互相发送的消息AnimationCard定义了一个可以播放 GIFs 动画和短视频的 cardAttachement定义了一个包含在消息中的额外的信息AudioCard定义了一个可以播放音频的 cardCardAction定义了一个可以执行的动作CardImage定义了一个可以显示在 card 上的图片ChannelAccount定义了一个机器人或用户在频道上的账户Conversation定义了你想要开始一个对话所涉及的机器人和用户ConversationAccount定义了一个在频道里的会话Error定义了一个错误Fact定义了一个包含一个 fact 的 key-value pairGeoCoordinates定义了一个使用 World Geodetic System（WSG84）获得的地理位置HeroCard定义了一个包含一张大的图片，标题，文字和动作按钮的 cardIdentification定义了 resource 的 identityMediaUrl定义了一个媒体资源的 URLMention定义了一个在会话中提到的用户或者机器人Place定义了一个在会话中提到的地点ReceiptCard定义了一个包含付款发票的 cardReceiptItem定义了发票的一行项目SignInCard定义了让用户登录一个服务的 cardThumbnailCard定义了一个包含缩略图，标题，文本和动作按钮的 cardThumbnailUrl定义了一个图片资源的 URLUserData定义了包含用户状态和首选项的用户数据VideoCard定义了一个可以播放视频的 card

Error codes

Connector 返回下边这些标准的 HTTP 状态代码。所有的错误 response 会包含一个 Error 对象，该对象包含了一段错误描述。

状态代码描述200请求成功201请求成功202请求已经被接受来进行下一步操作400请求是有缺陷的或者是不正确的401机器人无权限发出这个请求403机器人无权限发出这个请求404资源找不到500发生服务器内部错误503服务不可用