Alexa的语音服务(AVS)公开HTTP / 2端点和支持云启动指令,它允许您访问Alexa的内置功能,如定时器、报警器、媒体传输控制,语音控制音量调节,和亚马逊的Alexa的应用集成。
关键术语和概念
Frame:在HTTP/2协议的基本单元;每一个Frame都有不同的用途,例如标题和数据的Frame格式的HTTP请求和响应的基础。
流:一个独立的、双向的帧序列的一个客户端和服务器之间交换在一个HTTP / 2连接。
接口:AVS暴露接口(speechrecognizer,AudioPlayer,synchronizestate,等),提供您的产品使用Alexa的内置的技能。
Downchannel(下载通道):在你的HTTP / 2连接创建的一个流,它是用来传递指令从云端到你的客户。下载通道仍然开放,在半封闭的状态从设备和开放从AVS为连接的生命周期。下载通道主要是用来发送指令和音频附件云启动你的客户端。
注意:你的客户端每个连接只能创建一个下载通道流。
云启动指令:从云发送到客户端的指令。例如,当用户使用亚马逊Alexa的APP调整设备的音量,直接发送到你的产品不需要相应的语音请求。
先决条件
在创建一个与AVS的HTTP / 2连接,你需要:
获取访问令牌
使用AVS标准,您的产品需要获得亚马逊登录(LWA)访问令牌,使您的产品获得API代表客户。有用于获得与AVS使用访问令牌的两种方法。
远程授权用于授权使用同伴网站或移动应用程序的设备。
从同伴站点授权
从同伴应用程序授权
本地授权用于授权Alexa直接从AVS功能的产品。
从AVS授权产品
LWA访问令牌你获得必须发送到AVS在每个事件的标题。如果认证以任何理由,AVS连接关闭失败。
下面是一个示例头。除了你的访问令牌,一个边界条件是每个事件的头需送到AVS。
:method = POST
:scheme = https
:path = /{{API version}}/events
authorization = Bearer {{YOUR_ACCESS_TOKEN}}
content-type = multipart/form-data; boundary={{BOUNDARY_TERM_HERE}}
注:每个产品实例必须有一个唯一的deviceserialnumber,这是数据通过授权检测。
选择一个HTTP 2客户端库
下面的HTTP 2客户端库推荐使用AVS:
语言库:
C / C++ nghttp2
C / C++ curl and libcurl
Java OkHttp
Java Netty
Java Jetty
警告:如果使用libcurl,客户必须得到请求/平每5分钟保持连接。
Base URL
https://avs-alexa-na.amazon.com
创建一个HTTP / 2连接
它应该创建一个单一的http2 AVS连接。这个连接是用来处理所有的指令和事件,包括任何在下载通道流发送到你的客户。。
保持与AVS的连接需要两样东西:
下载通道流的建立
同步你的产品的组件状态与AVS(AudioPlayer,警报喇叭、SpeechSynthesizer)
建立一个下降通道流你的客户端必须得到请求(/{{API version}}/directives)在10秒内打开连接与AVS。请求应该这样:
:method = GET
:scheme = https
:path = /{{API version}}/directives
authorization = Bearer {{YOUR_ACCESS_TOKEN}}
一个成功的请求后,该下载通道流将在半敞开封闭状态从客户端开放AVS为连接的生命周期。这是不常见的云启动指令之间有很长的停顿。
在下载通道流的建立,客户必须同步它的组件的状态与AVS一致。这需要在现有连接上对新的事件流进行POST请求/{{API version}}/directives(注:不要打开新连接)。当客户端接收响应(指令)时,该事件流应该关闭。下面是一个例子synchronizestate事件:
:method = POST
:scheme = https
:path = /{{API version}}/events
authorization = Bearer {{YOUR_ACCESS_TOKEN}}
content-type = multipart/form-data; boundary={{BOUNDARY_TERM_HERE}}
--{{BOUNDARY_TERM_HERE}}
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8
{
"context": [
{{Alerts.AlertsState}},
{{AudioPlayer.PlaybackState}},
{{Speaker.VolumeState}},
{{SpeechSynthesizer.SpeechState}}
],
"event": {
"header": {
"namespace": "System",
"name": "SynchronizeState",
"messageId": "{{STRING}}"
},
"payload": {
}
}
}
--{{BOUNDARY_TERM_HERE}}--
同步状态后,客户端应该能够使用此连接到:
发送事件和AVS接收指令
注意:每个事件及其相关响应都发送到单个事件流上。接收响应时,应关闭流,
在下载通道流接收云启动指令
保持一个HTTP / 2连接
一旦你已经建立了一个连接,重要的是要了解如何管理事件流,流的下降通道,ping,超时和服务器发起断开。
需要考虑的事情
我们鼓励流捕获音频AVS 10块320字节(320字节的数据帧发送单个单位)。大数据块的大小,造成不必要的缓冲,负面地影响了AVS的处理音频的能力,可能会导致更高的延迟。
所有捕获的音频发送到AVS编码应为:
16bit线性PCM(lpcm16)
16khz采样率
单通道
小端字节序
AVS的http2连接只支持10并发流。这包括事件流的下载通道,与ping。请确保响应接收时关闭事件流。
许多库有一个读超时,一个客户端将尝试读取多长时间而不接收任何数据。由于AVS需要下载通道流需要保持开放的AVS和你的客户之间的连接的生命周期,这流可以长时间不发送任何数据到你的客户,你的阅读超时设置为至少60分钟,这是很重要的。
如果你的http2客户池或标记连接的空闲连接,调整超时,连接不中断是很重要的(如果是中断完成流程描述创建一个连接,其中包括:重新确立下载通道流和同步状态,AVS)。我们建议将超时设置为至少60分钟,以确保您的连接不会过早关闭
事件流的生命周期
每一个新的事件被发送到自己的流。通常,这些流在Alexa的语音服务已返回指令和相应的音频附件到你的客户。
请求按顺序处理。因此,新的请求应该发送后,Alexa开始回应你的请求(之前的请求返回头)。
你的产品打开一个流并发送一个多部分消息由一个JSON格式的事件到一个二进制音频附件(0或1)。
AVS的回报多部分消息由一个JSON格式的指令和对应的音频附件在同流,可能在流是完整的。如下的CID URL属性:在Play or Speaker指令也将出现在相关的音频连接头。
下面的一个响应从AVS的事件流应该关闭。
注:为你的客户接收多个指令,它是可能的(JSON)在接收相应的音频附件。因此,您的客户端应该有必要的逻辑,以配合指令与相应的音频附件
下载通道的生命周期
并行,指令可能在下降通道发送给你的客户。主要的下降通道,用于云启动指令。
一个GET请求作出指示的路径在10秒内创造与AVS的连接。
这流是用来发送您的客户云启动指令和音频附件,如定时器、报警器、指示来自亚马逊的Alexa的APP。不像一个事件流的下降通道,不立即关闭,目的是在半封闭状态保持开放在客户端保持A长时间打开AVS。
当下降通道流关闭,您的客户必须立即建立你的客户能接受云发起指令新的下降通道
ping和超时
您的客户必须执行下列操作之一,没有这样做将导致一个封闭的连接:
空闲时每5分钟ping一次AVSFrame
当连接空闲时,每5分钟一次GET请求/ ping。
请求实例:
:method = GET
:scheme = https
:path = /ping
authorization = Bearer {{YOUR_ACCESS_TOKEN}}
在一个失败的ping应该关闭连接和一个新的连接应该立即创建。
警告:如果使用libcurl,客户必须得到请求/平每5分钟保持连接
服务器启动断开
当服务器启动断开连接时,客户端应:
打开一个新的连接,并通过它路由任何新的请求。
在打开所有请求后,关闭旧连接,相应的流已被关闭。
与断开连接之前建立的任何流URL保持连接(例如亚马逊音乐、音频等)。在服务器启动断开之前发生的流应继续播放,只要字节可用。
如果尝试创建新连接失败,则客户端将重试以指数回退。