传输层协议

摘要

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。

Ping

为了保持物理连接不断，设备端应该周期性的（建议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请求失败，设备端应该立即关闭当前的物理连接，建立一个新的连接并创建下行消息通道。

总结

简单总结服务连接步骤：

1. 设备端连上网络之后，立即与服务端建立HTTP/2连接(此连接为唯一物理连接），连接内创建一个数据流并发送GET /dcs/v1/directives请求，此数据流为DCS下行消息通道，一直保持“半打开状态”
2. 在设备端需要上报事件时，在唯一物理连接内部创建新的数据流，发送POST /dcs/v1/events请求；请求/响应结束后关闭该数据流
3. 每1分钟，在唯一物理连接内部，创建新的数据流，发送GET /ping请求；请求/响应结束后关闭该数据流。ping的请求，会作为设备在线状态的依据之一。一段时间没有收到ping，服务端会认为设备处于离线状态。

HTTP/2客户端库

HTTP/2的客户端无需自行开发，可使用现成的库，一些常用的库如下：

• C/C++
  • Nghttp2
  • curl / libcurl
• Java
  • OkHttp
  • Jetty

如果需要其他语言或者有其他需求，在github还能找到更多HTTP/2的客户端库。