Embedded API v1 介绍

说明

嵌入式协议（Embedded iFLYOS Voice Service， 简称EVS）是一个相对IVS更简单的协议，为厂商接入提供方便，降低设备运行要求，本协议采取websocket进行通讯。

• 创建设备
• 授权认证
• 连接协议 - 使用 WebSocket 连接到 iFLYOS
• 交互协议说明
  • 设备发送给iFLYOS云端的请求
  • iFLYOS云端发送给设备的回复
• 功能模块说明

创建设备

在使用EVS协议接入iFLYOS前，需要先在设备接入控制台 (opens new window)创建设备。点击查看创建流程

授权认证

连接到 iFLYOS 之前，你需要做以下动作

1. 通过设备接入平台 (opens new window)添加一个嵌入式API版本的设备
2. 参考设备认证授权文档 (opens new window)实现设备端的授权功能流程，获取对应Token信息

根据上面的指南你能获取到两个 Token 信息分别是：access_token，refresh_token；同时也会获取到一个 expires_in。

{
  "token_type": "bearer",
  "refresh_token": "4_vujpFOfu0G5yf4**************DwX5S80s74CY7",
  "expires_in": 86400000,//单位秒
  "created_at": 1526485197,//单位秒
  "access_token": "bd6XMEqzIokI6mnMM**************iKAdYNa9T-1WXY"
}

参数	类型	说明	是否必需
token_type	string	取值：bearer或jwt，当前仅支持bearer	是
access_token	string	在建立 websocket 连接时和每次发送 request 时需要使用	是
expires_in	long	access_token的有效时长，单位为秒	是
created_at	long	令牌创建时间，unix时间戳，单位为秒	是
refresh_token	string	令牌刷新token	是

你的系统需要通过 created_at 和 expires_in 以及当前时间来判断 access_token 的有效期，并且及时刷新，下面我们提供一个使用 javascript 来判断的 token 的时候刷新的代码

let expires_in = 86400000//单位秒
let created_at = 1526485197//单位秒
let expires_time = expires_in + created_at

let time_now = Math.floor(Date.now() / 1000)

// token还有一个小时要过期
if (expires_time - time_now < 3600) {
  // 调用刷新 access_token 接口，使用 refresh_token 刷新token信息；
  // 保存刷新后的token信息，包括 expires_in 等信息；
}
// 使用最新access_token执行

连接协议 - 使用 WebSocket 连接到 iFLYOS

1. device_id 是指每个设备的唯一标识，一般使用设备的 SN 码即可；（为了确保设备上的接口不被破解滥用，请将 device_id 提交到设备接入控制台 (opens new window)，iFLYOS将会在设备授权、连接时，进行验证，非白名单设备将无法使用iFLYOS）

2. 将上面步骤获取的 access_token 和 device_id 作为URL参数，连接websocket：

   安全地址：wss://ivs.iflyos.cn/embedded/v1?token={access_token}&device_id={device_id}

   非安全地址：ws://ivs.iflyos.cn/embedded/v1?token={access_token}&device_id={device_id}

注意

我们建议你选择安全地址(wss)接入iFLYOS，除非设备本身有无法解决的限制。若你的设备选择接入非安全地址(ws)，在设备提交审核时，请说明为什么接入非安全的协议(ws)，否则OS运营团队将不会通过你的设备审核。

交互协议说明

设备发送给iFLYOS云端的请求

iFLYOS 中，我们把设备发送到服务端的指令称为请求(request)，一次发送一个请求object，每次发送请求时，均需要同步发送iflyos_header和iflyos_context。

{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {...}
}

构建通用请求的iflyos_header

iflyos_header 中的内容为向云端报告本次请求来源（如硬件设备）的基础信息，具体包含的内容如下：

"iflyos_header": {
  "authorization": "Bearer xxxxxx",
  "device":{
    "device_id": "xxxxxxx",
    "ip": "xxx.xxx.xxx.xxx",
    "location": {
      "latitude": 132.56481,
      "longitude": 22.36549
   },
    "platform": {
      "name": "android",
      "version": "8.0.1"
   }
 }
}

参数	类型	说明	必填
authorization	String	用户的access_token，每一次都需要带上去，用于用户鉴权，需要参考上文方法避免 token 过期	是
device	Object	设备信息	是
device.device_id	String	设备的唯一标识，正式环境请使用设备唯一的SN码	是
device.ip	String	设备公网IP，若设备无法获取，可不填	否
device.location	Object	设备的位置信息，设备端可通过GPS获取或在配网时候从手机获取后写入设备中	否
device.location.latitude	Float	纬度和 longitude 成对出现	否
device.location.longitude	Float	经度和 latitude 成对出现	否
device.platform	Object	设备系统平台信息	是
device.platform.name	String	系统平台名称。取值：android, linux, ios。请注意：全部字母均为小写	是
device.platform.version	String	系统平台版本	是

构建通用请求 iflyos_context

iflyos_context 用于向云端同步当前的设备状态，以功能模块为区分，代表发送请求时设备最新的信息。每次对服务端发起的请求都要包含它，iflyos_context 中需要包含所有已经实现的设备模块的信息。

"iflyos_context": {
  "system": {...},
  "recognizer": {...},
  "speaker": {...},
  "audio_player": {...},
  "alarm": {...},
  "screen": {...},
  "template": {...},
  "video_player": {...},
  "app_action": {...},
  "playback_controller": {...},
  "launcher": {...},
  "interceptor": {...}
}

参数	类型	说明	必填
system	Object	系统信息。点击查看详情	是
recognizer	Object	语音识别器信息。点击查看详情
speaker	Object	扬声器信息。点击查看详情	否
audio_player	Object	音频播放器信息。点击查看详情	是
alarm	Object	设备闹钟信息，若未实现设备闹钟，该项可不出现。点击查看详情	否
screen	Object	设备屏幕信息，若设备无屏，该项可不出现。点击查看详情	否
template	String	设备模板显示信息。若设备不实现云端模板，该项可不出现。点击查看详情	否
video_player	Object	视频播放器。若设备不支持视频播放，该项可不出现。点击查看详情	否
app_action	Object	app操作。若设备不支持（非安卓设备），该项可不出现。点击查看详情	否
playback_controller	Object	播放控制。若设备没实现音频播放或视频播放，该项可不出现。点击查看详情	否
launcher	Object	启动器。若设备不支持启动器页面跳转等能力，该项可不出现。点击查看详情	否
interceptor	Object	用于拦截器的上下文。若设备未使用云端拦截器，该项可不出现。点击查看详情	否

iFLYOS云端发送给设备的回复

iFLYOS 中，我们把设备接收到服务端的指令称为响应(response)，一次收到一个iflyos_meta和iflyos_response集，设备需要按iflyos_response列表顺序执行操作。

{
  "iflyos_meta": {...},
  "iflyos_responses": [
    {
      "header": {
        "name": "xxx"
      },
      "payload": {...}
    },
    {
      "header": {...},
      "payload": {...}
    }
  ]
}

解析通用回复的 iflyos_meta

iflyos_meta 中主要是云端回复的元数据，代表本次回复是对某一个request的回复。

{
  "iflyos_meta": {
    "trace_id": "xxxxxx",
    "request_id": "xxxxx", //当云端主动发送response时，该字段不会出现
    "is_last": true //标记这组回复是不是这个request_id关联的最后一组回复
  }
}

参数	类型	说明	必须出现
trace_id	String	本次交互的跟踪标识，提技术支持工单时可能会用到，建议打印在系统日志中	是
request_id	String	本次回复对应的请求的唯一标识，与request中的request_id一致。当云端主动发送response时，该字段不会出现	否
is_last	Bool	标记本次回复是不是这个请求的最后一组回复	是

注意：设备请求发送成功，但云端不返回执行时，会返回如下的结果：

{
  "iflyos_meta": {
    "trace_id": "xxxxxx",
    "request_id": "xxxx",
    "is_last": true
  },
  "iflyos_responses": []
}

功能模块说明

注意

• 以下要求必须实现的request和response，如果不按需求实现，iFLYOS的运营人员将会在审核时拒绝你的请求。
• 以下可选实现的request和response，你可以根据自身设备的需求进行实现。

name	说明	实现要求
recognizer	语音识别器，这是iFLYOS交互的基础	必须实现
audio_player	音频播放器，播放的内容可能是音乐、新闻、闹钟响铃或TTS语音	必须实现
system	系统相关	必须实现
alarm	设备本地闹钟	可选实现
speaker	扬声器控制	可选实现
video_player	视频播放器，	可选实现
playback_controller	播放控制，在部分场景下，用户可通过触控或按键控制音频播放进度	可选实现
app_action	APP操作，针对系统的第三方APP进行的操作	可选实现
screen	屏幕控制	可选实现
template	模板展示，用于通过界面模板给用户反馈更丰富的信息	可选实现
launcher	启动器	可选实现
interceptor	自定义拦截器，是iFLYOS 实现自定义语义理解的基础	可选实现