Http接口协议定义

消息格式

请求头部

content-type: application/x-www-form-urlencoded

请求前应对参数进行urlencode，将encode后的参数拼接在url中。

例如/intent/invoke请求，有如下参数：
params - {"osClientId":"os.client.sdkdemo","deviceType":1,"productId":"N_PROD1_7","sn":"test","xn":"781f7740","deviceId":"demo-device-id","lat":"12.3","lng":"32","version":"1.2","osVersion":"2.3","dt":23123123123,"sysType":1,"appVersion":"1.0","sysVersion":"2.0","osAccessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvcy5jbGllbnQuc2RrZGVtbyIsInVpZCI6MCwiaXNzIjoieHktb3MtdWNlbnRlciIsImV4cCI6MTU2NDY1OTAyMywiZGV2aWNlSWQiOiJkZW1vLWRldmljZS1pZCJ9.vJYrYRiiFIycYwiRD5BK2LQfmlwEqHSlBO8cSAlLa6c"}
intent - {"domain":"xima","intent":"get_tracks_by_album_id","slots":{"id":"12488804","contextSorted":false}}
session - {"attributes":{"a":"b"},"sid":"e41e68d73b48158b717affaee8f912"}

将所有参数urlencode后的结果为：
params - %7b%22osClientId%22%3a%22os.client.sdkdemo%22%2c%22deviceType%22%3a1%2c%22productId%22%3a%22N_PROD1_7%22%2c%22sn%22%3a%22test%22%2c%22xn%22%3a%22781f7740%22%2c%22deviceId%22%3a%22demo-device-id%22%2c%22lat%22%3a%2212.3%22%2c%22lng%22%3a%2232%22%2c%22version%22%3a%221.2%22%2c%22osVersion%22%3a%222.3%22%2c%22dt%22%3a23123123123%2c%22sysType%22%3a1%2c%22appVersion%22%3a%221.0%22%2c%22sysVersion%22%3a%222.0%22%2c%22osAccessToken%22%3a%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvcy5jbGllbnQuc2RrZGVtbyIsInVpZCI6MCwiaXNzIjoieHktb3MtdWNlbnRlciIsImV4cCI6MTU2NDY1OTAyMywiZGV2aWNlSWQiOiJkZW1vLWRldmljZS1pZCJ9.vJYrYRiiFIycYwiRD5BK2LQfmlwEqHSlBO8cSAlLa6c%22%7d
intent - %7b%22domain%22%3a%22xima%22%2c%22intent%22%3a%22get_tracks_by_album_id%22%2c%22slots%22%3a%7b%22id%22%3a%2212488804%22%2c%22contextSorted%22%3afalse%7d%7d
session - %7b%22attributes%22%3a%7b%22a%22%3a%22b%22%7d%2c%22sid%22%3a%22e41e68d73b48158b717affaee8f912%22%7d

拼接url后结果：
https://api.xiaoyastar.com/intent/invoke?params=%7b%22osClientId%22%3a%22os.client.sdkdemo%22%2c%22deviceType%22%3a1%2c%22productId%22%3a%22N_PROD1_7%22%2c%22sn%22%3a%22test%22%2c%22xn%22%3a%22781f7740%22%2c%22deviceId%22%3a%22demo-device-id%22%2c%22lat%22%3a%2212.3%22%2c%22lng%22%3a%2232%22%2c%22version%22%3a%221.2%22%2c%22osVersion%22%3a%222.3%22%2c%22dt%22%3a23123123123%2c%22sysType%22%3a1%2c%22appVersion%22%3a%221.0%22%2c%22sysVersion%22%3a%222.0%22%2c%22osAccessToken%22%3a%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvcy5jbGllbnQuc2RrZGVtbyIsInVpZCI6MCwiaXNzIjoieHktb3MtdWNlbnRlciIsImV4cCI6MTU2NDY1OTAyMywiZGV2aWNlSWQiOiJkZW1vLWRldmljZS1pZCJ9.vJYrYRiiFIycYwiRD5BK2LQfmlwEqHSlBO8cSAlLa6c%22%7d&intent=%7b%22domain%22%3a%22xima%22%2c%22intent%22%3a%22get_tracks_by_album_id%22%2c%22slots%22%3a%7b%22id%22%3a%2212488804%22%2c%22contextSorted%22%3afalse%7d%7d&session=%7b%22attributes%22%3a%7b%22a%22%3a%22b%22%7d%2c%22sid%22%3a%22e41e68d73b48158b717affaee8f912%22%7d

公共参数

params

字段必填类型说明
osAccessToken是String小雅OS访问令牌，登陆时非必填
deviceType是Integer请求来源：1-app端 2-设备端，填写客户端的，不是服务器的信息
productId是String产品ID，小雅OS开放平台创建设备后获取
sn是String设备sn，若deviceType != 2 时非必填
xn否String设备校验码，/account/sn-login接口必需
deviceId是Stringapp设备号，若deviceType != 1 时非必填
lat否String纬度，如果有建议上报，部分技能会根据地理位置进行逻辑处理
lng否String经度
sysType是Integer手机系统类型：1-Android 2-IOS，若deviceType != 1 时非必填
appVersion是String手机应用版本号，若deviceType != 1 时非必填
sysVersion是String手机系统版本号，若deviceType != 1 时非必填
speakerVersion是String对应的设备版本号，若deviceType != 2时非必填
romVersion是String对应的设备rom版本号，若deviceType != 2时非必填
dt是long毫秒unix时间戳

session

字段类型必填说明
sessionJsonObject是会话信息
session.sidString是session id
session.attributesJsonObject否会话属性，部分技能可能有值，key-value形式，key为string，value为object

sig

参数签名，生成方法参见签名规则

交互逻辑

客户端在请求服务前应先登录，获取小雅OS的访问令牌(osAccessToken)，持有访问令牌的请求才有权限访问小雅OS的服务。 请求HTTP API的响应，即当前请求的结果。

小雅OS HTTP API提供的服务包括：基于文字的NLU解析、TTS合成，以喜马拉雅有声内容为代表的多种技能。

小雅OS提供了一个业务处理API(intent/invoke)，其集成了所有业务请求的处理；不同的业务请求以Domain/Intent/Slot参数加以区分， Domain/Intent/Slot是NLU解析结果的常见表示形式，这里Domain表示业务领域，Intent表示具体业务，二者唯一决定请求的业务及API返回格式，Slot表示业务请求的参数，其决定业务返回的结果。

例如：请求专辑下的声音列表，对应的Domain为xima，Intent为get_tracks_by_album_id，Slot槽位参数有专辑id(id)、内容是否有序(contextSorted)， 将Domain/Intent/Slot组合成intent参数 - intent={"domain":"xima","intent":"get_tracks_by_album_id","slots":{"id":"12488804","contextSorted":false}}，请求intent/invoke接口，返回查询结果。

urlencode前的url如下所示：

https://api.xiaoyastar.com/intent/invoke?params={"osClientId":"os.client.sdkdemo","deviceType":1,"productId":"N_PROD1_7","sn":"test","xn":"781f7740","deviceId":"demo-device-id","lat":"12.3","lng":"32","version":"1.2","osVersion":"2.3","dt":23123123123,"sysType":1,"appVersion":"1.0","sysVersion":"2.0","osAccessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvcy5jbGllbnQuc2RrZGVtbyIsInVpZCI6MCwiaXNzIjoieHktb3MtdWNlbnRlciIsImV4cCI6MTU2NDY1OTAyMywiZGV2aWNlSWQiOiJkZW1vLWRldmljZS1pZCJ9.vJYrYRiiFIycYwiRD5BK2LQfmlwEqHSlBO8cSAlLa6c"}&intent={"domain":"xima","intent":"get_tracks_by_album_id","slots":{"id":"12488804","contextSorted":false}}&session={"attributes":{"a":"b"},"sid":"e41e68d73b48158b717affaee8f912"}

Domain/Intent与业务的对应关系详见技能业务数据

签名规则

每次访问需要签名sig，生成算法描述和示例如下:

将所有请求参数的原始值按照参数名字的字典序排序：

text:今天天气怎样
session: {"attributes":{"a":"b"},"sid":"111"}
params: {"osAccessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJTX1BST0QyMDAwMDEiLCJ1aWQiOjEyMzQ1LCJpc3MiOiJ4eS1vcy11Y2VudGVyIiwiZXhwIjoxNTUyMjQ2MzYyfQ.GqQ5yon0_drUMJR00aQPhdQY_CJRWfNesMZZG-mkEHY","deviceType":2,"productId":"S_PROD200001","sn":"aaaa","xn":"781f77405e7e0140a365a47a418ac8fb","deviceId":"aaa","lat":"12.3","lng":"32","version":"1.2","osVersion":"2.3","dt":23123123123}

将排序后的参数键值对用&号拼接，即拼接成如下这样的形式：

params={"osAccessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJTX1BST0QyMDAwMDEiLCJ1aWQiOjEyMzQ1LCJpc3MiOiJ4eS1vcy11Y2VudGVyIiwiZXhwIjoxNTUyMjQ2MzYyfQ.GqQ5yon0_drUMJR00aQPhdQY_CJRWfNesMZZG-mkEHY","deviceType":2,"productId":"S_PROD200001","sn":"aaaa","xn":"781f77405e7e0140a365a47a418ac8fb","deviceId":"aaa","lat":"12.3","lng":"32","version":"1.2","osVersion":"2.3","dt":23123123123}
&session={"attributes":{"a":"b"},"sid":"111"}&text=今天天气怎样

将上一步中得到的字符串拼上对应的secret, 使用productSecret, 则现在得到的拼接结果为：

params={"osAccessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJTX1BST0QyMDAwMDEiLCJ1aWQiOjEyMzQ1LCJpc3MiOiJ4eS1vcy11Y2VudGVyIiwiZXhwIjoxNTUyMjQ2MzYyfQ.GqQ5yon0_drUMJR00aQPhdQY_CJRWfNesMZZG-mkEHY","deviceType":2,"productId":"S_PROD200001","sn":"aaaa","xn":"781f77405e7e0140a365a47a418ac8fb","deviceId":"aaa","lat":"12.3","lng":"32","speakerVersion":"1.2","romVersion":"2.3","dt":23123123123}
&session={"attributes":{"a":"b"},"sid":"111"}&text=今天天气怎样&productSecret=OiJIUzI1NiIsInR5cCI

对上一步中得到的字符串进行MD5运算得到32位小写字符串，即为sig的值

60b0abdee2c155d8445e95acf1847284
← WebSocket接口协议定义调用样例 →