API 参考 - Direct Line API 3.0

项目
10/28/2024

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

基本 URI

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

对于全局机器人，请使用 https://directline.botframework.azure.cn
对于区域机器人，请根据所选区域输入以下 URI：

区域基 URI

欧洲 https://europe.directline.botframework.azure.cn

印度 https://india.directline.botframework.azure.cn

区域	基 URI
欧洲	`https://europe.directline.botframework.azure.cn`
印度	`https://india.directline.botframework.azure.cn`

提示

如果对区域机器人使用全局基础 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	不允许客户端执行请求的操作。操作可能会失败，原因如下。无效的令牌：当请求使用以前有效但已过期的令牌时，在 ErrorResponse 对象中返回的 Error 的 `code` 属性被设置为 `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.azure.cn/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 字符。建议将活动控制在 150K 以下。如果需要更多数据，请考虑拆分活动或使用附件。

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

其他资源

Bot Framework 活动规范