Share via

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

API 参考 - Direct Line API 3.0

  • 项目

可以使用 Direct Line API 3.0 通过客户端应用程序与机器人通信。 Direct Line API 3.0 通过 HTTPS 使用行业标准的 REST 和 JSON。

基本 URI

若要访问 Direct Line API 3.0，请对所有 API 请求使用以下基 URI 之一：

提示

如果对区域机器人使用全局基 URI，请求可能会失败，因为某些请求可能超出地理边界。

头文件

除了标准 HTTP 请求标头，Direct Line API 请求还必须包含一个 Authorization 标头，用于指定对发出请求的客户端进行身份验证所需的机密或令牌。 使用以下格式指定 Authorization 标头：

Authorization: Bearer SECRET_OR_TOKEN

若要详细了解如何获取可供客户端用于进行 Direct Line API 请求身份验证的机密或令牌，请参阅身份验证。

HTTP 状态代码

随每个响应返回的 HTTP 状态代码指示相应请求的结果。

HTTP 状态代码 含义
200 请求成功。
201 请求成功。
202 已接受请求，将进行处理。
204 请求成功，但未返回任何内容。
400 请求格式不正确或者其他方面不正确。
401 客户端无权发出请求。 通常情况下，出现此状态代码是因为 Authorization 标头缺失或格式不正确。
403 不允许客户端执行请求的操作。 由于以下原因，该操作可能会失败。
  • 无效令牌：当请求使用以前有效但已过期的令牌时，codeErrorResponse 对象中返回的错误属性将设置为 TokenExpired。
  • 数据边界冲突：如果机器人是区域机器人，但基本 URI 不是区域，则某些请求可能会超出地理边界。
  • 无效的目标资源：目标机器人或站点无效或已删除。
404 找不到请求的资源。 通常情况下，此状态代码指示请求 URI 无效。
500 Direct Line 服务中发生了内部服务器错误。
502 机器人不可用或返回了错误。 这是常见错误代码。

注意

HTTP 状态代码 101 在 WebSocket 连接路径中使用，尽管 WebSocket 客户端很有可能会处理此代码。

错误

指定 4xx 范围或 5xx 范围内的 HTTP 状态代码的任何响应都将在响应正文中包含 ErrorResponse 对象，该对象提供错误相关信息。 如果收到 4xx 范围内的错误响应，请检查 ErrorResponse 对象以确定错误原因，并在重新提交请求之前解决问题。

注意

在 ErrorResponse 对象内的 code 属性中指定的 HTTP 状态代码和值是稳定的 。 在 ErrorResponse 对象内的 message 属性中指定的值可能会随时间而变化 。

以下片段显示了示例请求和生成的错误响应。

请求

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

响应

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

令牌操作

使用以下操作创建或刷新可供客户端用来访问单个聊天的令牌。

Operation 说明
生成令牌 生成适用于新聊天的令牌。
刷新令牌 刷新一个令牌。

生成令牌

生成对一个聊天有效的令牌。

POST /v3/directline/tokens/generate
内容 说明
请求正文 一个 TokenParameters 对象
返回 Conversation 对象

刷新令牌

刷新令牌。

POST /v3/directline/tokens/refresh
内容 说明
请求正文 不适用
返回 Conversation 对象

聊天操作

使用以下操作与机器人开启聊天，并在客户端和机器人之间交换活动。

Operation 说明
启动聊天 与机器人开启新的聊天。
获取聊天信息 获取现有聊天的相关信息。 此操作生成客户端可用于重新连接到聊天的新 WebSocket 流 URL。
获取活动 从机器人检索活动。
发送活动 向机器人发送活动。
上传和发送文件 以附件形式上传和发送文件。

启动聊天

与机器人开启新的聊天。

POST /v3/directline/conversations
内容 说明
请求正文 一个 TokenParameters 对象
返回 Conversation 对象

获取聊天信息

获取有关现有聊天的信息，并生成客户端可用于重新连接到聊天的新 WebSocket 流 URL。 可以选择提供请求 URI 中的 watermark 参数，以指示客户端看到的最新消息。

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
内容 说明
请求正文 不适用
返回 Conversation 对象

获取活动

从机器人检索指定聊天的活动。 可以选择提供请求 URI 中的 watermark 参数，以指示客户端看到的最新消息。

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
内容 说明
请求正文 不适用
返回 ActivitySet 对象。 此响应包含的 watermark 用作 ActivitySet 对象的属性。 客户端应通过增加 watermark 值来浏览可用活动，直到不返回任何活动。

发送活动

向机器人发送活动。

POST /v3/directline/conversations/{conversationId}/activities
内容 说明
请求正文 Activity 对象
返回 将 ResourceResponse 发送到机器人，其中包含指定活动 ID 的 id 属性。

上传和发送文件

以附件形式上传和发送文件。 在请求 URI 中设置 userId 参数，以便指定发送附件的用户的 ID。

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
内容 说明
请求正文 对于单个附件，请在请求正文中填充文件内容。 对于多个附件，请创建一个多部件请求正文，将其中的一个部件用于每个附件，并选择性地将另一个部件用于 Activity 对象，该对象应该充当指定附件的容器。 有关详细信息，请参阅向机器人发送活动。
返回 将 ResourceResponse 发送到机器人，其中包含指定活动 ID 的 id 属性。

注意

上传的文件在 24 小时后删除。

架构

Direct Line 3.0 架构包含 Bot Framework 架构定义的所有对象，以及特定于 Direct Line 的某些对象。

ActivitySet 对象

定义一组活动。

properties 类型​​ 说明
activities Activity[] Activity 对象的数组 。
watermark 字符串 集内活动的最大水印。 客户端可以使用 watermark 值来指示从机器人检索活动时或生成 WebSocket 流 URL 时所看到的最新消息。

Conversation 对象

定义 Direct Line 聊天。

properties 类型​​ 说明
conversationId 字符串 一个 ID，可以唯一标识指定的令牌所适用的聊天。
eTag 字符串 一个 HTTP ETag（实体标记）。
expires_in 数字 令牌过期前需经历的秒数。
referenceGrammarId 字符串 此机器人的参考语法的 ID。
streamUrl 字符串 聊天的消息流的 URL。
token 字符串 对指定的聊天有效的令牌。

TokenParameters 对象

用于创建令牌的参数。

properties 类型​​ 说明
eTag 字符串 一个 HTTP ETag（实体标记）。
trustedOrigins string[] 要嵌入到令牌中的受信任来源。
user ChannelAccount 要嵌入到令牌中的用户帐户。

活动

对于客户通过 Direct Line 从机器人接收的每个Activity：

  • 保留附件卡。
  • 以私有链接方式隐藏已上传的附件的 URL。
  • channelData 属性已保留且未经修改。

客户端可以从机器人接收多个活动作为 ActivitySet 的一部分。

客户端通过 Direct Line 向机器人发送 Activity 时：

  • 该 type 属性指定要发送的类型活动（通常是 消息）。
  • 必须使用客户端选择的用户 ID 填充 from 属性。
  • 附件可能包含现有资源的 URL 或通过 Direct Line 附件终结点上传的 URL。
  • channelData 属性已保留且未经修改。
  • 活动的总大小在序列化为 JSON 并加密后不得超出 256K 字符。 建议将活动保持在 15 万以下。 如果需要更多数据，请考虑将活动拆分或使用附件。

客户端可以为每个请求发送一个活动。

其他资源