HTTP 协议定义 · 小雅OS开放平台文档

在没有语音流数据传输时，小雅OS提供HTTP协议访问接口。

HTTP接口分为两个类型：单一功能API和技能内调用API，其中技能内调用API调用使用接口：serv/intent/invoke。

消息格式

请求头部

Content-Type: application/x-www-form-urlencoded # 如果Method是POST
Cache-Control: no-cache
Method: GET/POST # 根据接口不同而不同

公共参数

除账号对接外的大部分接口使用公共参数。

params

字段	必填	类型	说明
osOpenId	否	String	小雅OS用户唯一标识，见osOpenId，由serv/user接口返回
deviceType	是	Integer	请求来源客户端类型：1-伴侣端 2-设备端，请填写客户端的实际类型
productId	是	String	产品ID，小雅OS硬件开放平台创建设备后获取，获取过程：创建产品
sn	是	String	设备序列号，若deviceType为2时必填，由贵方自主生成，同一台设备请务必保持不变，登录信息与设备有关
deviceId	是	String	伴侣所在的手机序列号，若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时间戳

osAccessToken

接口鉴权令牌，有效期为2小时(请依据接口返回)，最大保有量为5个，更多详细规则及获取方法请见接口：/serv/account/os-access-token

返回值格式

返回值为JSON格式

交互逻辑

接口交互过程：

获取访问令牌：/serv/account/os-access-token
创建用户(用户小雅OS服务时创建即可)：serv/user
访问NLU接口：/serv/text/query
访问其他接口：/serv/intent/invoke

在交互过程中，/serv/text/query、/serv/intent/invoke等接口均涉及到Domain/Intent概念。

示例

以请求获取当前设备的资源包列表接口为例，假设已经获取好了相关参数：

osAccessToken: xxx
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: 123
    sysType: 1
    appVersion: 1.0
    sysVersion: 2.0

接口提供的intent参数值为：

{
  "domain":"xima",
  "intent":"get_resource_kits",
  "slots":{}
}

第一步：格式化参数

var osAccessToken = encodeURIComponent("xxx");
var 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":123,"sysType":1,"appVersion":"1.0","sysVersion":"2.0"}';
var e_params = encodeURIComponent(params);
var intent = '{"domain":"xima","intent":"get_resource_kits","slots":{}}';
var e_intent = encodeURIComponent(intent);

第二步：URL拼接

var url = "https://api.xiaoyastar.com/serv/intent/invoke?osAccessToken=" + osAccessToken + "&params=" + e_params + "&intent=" + e_intent;

第三步：发出请求即可。

postman

我们推荐使用postman进行接口调试。下载安装完成后，请下载以下两个postman配置文件：

请分别导入环境配置(教程)和接口(教程)，然后将你申请到的信息配置到postman中。

postman

然后选择正式环境：

postman

然后就可以按上面的顺序进行请求测试了。

postman