-
DuerOS开放平台
-
技能开放平台
-
自定义技能
- 自定义技能简介
- 自定义技能创建
-
有屏技能
-
技能交互模型
-
自定义技能协议
- 处理DuerOS发送的请求
-
技能部署
-
技能开发样例
- 账户关联
-
技能测试
-
技能发布
-
技能付费
-
个性化服务
-
内容播报技能
-
小技能
-
平台能力扩展
-
SDK
-
预览版功能
- 全双工(Preview)
-
APP技能(Preview)
-
-
智能家居开放平台
- 品牌使用规范
-
开发者服务条款
DCS设备通过HTTP/2与服务端进行通讯,设备与服务端始终保持连接状态,服务端通过此连接可主动向设备端下发指令,闹钟、VAD检测等功能都依赖于长连接。本页面详细介绍设备端与服务端的消息传输协议,介绍如何建立/保持连接、发送/接受消息。
DCS设备在开机连上网络之后,应立即向服务端建立一个HTTP/2的连接(connection),并发送GET请求。请求示例如下:
:method = GET
:path = /dcs/v1/directives
:scheme = https
host = dueros-h2.baidu.com
authorization = Bearer {{ACCESS_TOKEN}}
dueros-device-id = {{DEVICE_UNIQUE_ID}}
此GET请求创建的数据流(stream)为DCS下行消息通道(down channel),服务端不会马上进行响应,而是一直保持通道打开状态,在服务端需要主动向设备端下发指令时,服务端将通过这个下行消息通道下发。
设备端发送GET请求之后,数据流应该保持“半打开状态”,即请求发送之后设备端的输出数据流(output stream)即可关闭,但输入数据流(input stream)应保持打开状态,随时准备接受服务端的响应,收到服务端下发的指令随时进行处理。如果设备所使用的HTTP/2连接库有读超时(read timeout),建议读超时时间设置成至少60分钟以上。为了保持连接状态,如果设备所使用的HTTP/2连接库有连接超时(connection timeout),建议超时时间设置成至少60分钟以上。
每一个设备端应该仅创建一个连接一个下行消息通道,并始终保持连接和通道畅通状态。如果下行消息通道被断开(或被服务端关闭),设备端应关闭当前连接,建立一个新的连接并创建新的下行消息通道。
在设备端发生任何事件时,设备端通过POST请求向服务端上报事件。请求示例如下:
:method = POST
:path = /dcs/v1/events
:scheme = https
host = dueros-h2.baidu.com
authorization = Bearer {{ACCESS_TOKEN}}
dueros-device-id = {{DEVICE_UNIQUE_ID}}
content-type = multipart/form-data; boundary=this-is-a-boundary
--this-is-a-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8
{{DCS_REQUEST}}
--this-is-a-boundary--
HTTP/2协议支持多路复用技术(multiplexing),即在同一个物理连接(connection)下,可以创建多个独立数据流(stream),每一个数据流都可以独立进行请求与响应。
DCS利用HTTP/2的多路复用技术,把创建下行消息通道时建立的物理连接,作为唯一的物理连接复用,设备端后续所有的请求和响应都应该复用该物理连接。在需要上报事件时,设备端应该在上述物理连接内部创建新的数据流,发送请求,并在收到服务端响应之后把数据流及时关闭。注意,是关闭为本次请求/响应所创建的数据流,而不是关闭连接本身,连接应该始终保持连接状态。
DCS事件分为交互事件和统计事件,交互事件的上报path为/dcs/v1/events, 统计事件的上报path为/dcs/v2/events。
为了保持物理连接不断,设备端应该周期性的(建议1分钟),在唯一物理连接内创建新的数据流,并向服务端发送Ping请求。请求示例如下:
:method = GET
:path = /dcs/v1/ping
:scheme = https
host = dueros-h2.baidu.com
authorization = Bearer {{ACCESS_TOKEN}}
dueros-device-id = {{DEVICE_UNIQUE_ID}}
请求成功后数据流关闭,物理连接保持连接状态。如果Ping请求失败,设备端应该立即关闭当前的物理连接,建立一个新的连接并创建下行消息通道。
简单总结服务连接步骤:
- 设备端连上网络之后,立即与服务端建立HTTP/2连接(此连接为唯一物理连接),连接内创建一个数据流并发送GET /dcs/v1/directives请求,此数据流为DCS下行消息通道,一直保持“半打开状态”
- 在设备端需要上报事件时,在唯一物理连接内部创建新的数据流,发送POST /dcs/v1/events请求;请求/响应结束后关闭该数据流
- 每1分钟,在唯一物理连接内部,创建新的数据流,发送GET /ping请求;请求/响应结束后关闭该数据流。ping的请求,会作为设备在线状态的依据之一。一段时间没有收到ping,服务端会认为设备处于离线状态。
HTTP/2的客户端无需自行开发,可使用现成的库,一些常用的库如下:
- C/C++
- Java
如果需要其他语言或者有其他需求,在github还能找到更多HTTP/2的客户端库。