设备能力API

IVS的为了支持新特性,设备能力可能会增加或更新。设备能力API可以区分每个设备支持的设备能力及其版本,从而实现针对特定产品进行OTA的灵活性。

报告设备能力API

调用场景

调用该接口主要是为了让【IVS】可以知道你的设备能处理哪些设备能力,可以为具有不同设备能力的设备提供更好的服务。你不需要经常调用这个接口,建议根据以下情况来调用:

  • 当设备首次通过用户授权获取到AccessToken后,连接 IVS 服务之前,调用此接口;
  • 当你的设备升级启动后,调用此接口;
  • 如果设备可以保存最后一次上报的设备能力信息,那只需要在设备能力有变化时,调用接口;
  • 如果你无法保存最后一次上报的设备能力信息,那你应该在设备启动或者升级后,调用接口;

注意

你没有必要在每次【刷新Token】后,或者连接到【IVS】前,都调用该接口。

响应说明

接口调用成功后,我们会返回HTTP状态码204。如果接口返回500,可以在1秒后重试,重试间隔以指数方式增加(2、4、8、16、32...256秒),重试间隔保持在最大256秒,一直重试直到返回204

设备能力版本

当服务端对设备能力的使用进行修改或者升级时,就会增加一个设备能力版本号,版本号格式为:主版本.次版本,如:1.2

次版本

次要版本修改会向后兼容,主要是对设备能力的升级,但对旧的版本内容不会有影响,一般我们会在这种情况下进行将次要版本的升级:

  • 该设备能力增加新的Directive或者 { Unknown macro: {Event}}

  • 原来的Directive或者Event增加新的字段

比如,System设备能力,增加ReportSoftwareInfo的指令,将版本从1.0升级到1.1,目的是为了让服务端能尽量实时的了解设备软件信息,但如果旧版本的设备,收到该指令时,并不会对其造成影响(直接忽略该指令)。

主版本

当设备能力有了破坏性的更改时,会更新主版本号,一般下面的情况会更新主版本:

  • 该设备能力删除新的Directive或者 Event

  • 改变了Directive或者Event某个参数的数据类型、含义

  • 删除了Directive或者Event的某个参数

设备能力版本号说明

Interface 当前版本 支持版本 必须出现
语音识别SpeechRecognizer 1.1 1.0, 1.1
语音合成SpeechSynthesizer 1.0 1.0
扬声器Speaker 1.0 1.0
闹钟提醒Alerts 1.0 1.0
音频播放器AudioPlayer 1.0 1.0
播放控制PlaybackController 1.0 1.0
模板消息TemplateRuntime 1.2 1.0, 1.1, 1,2 可选
勿扰模式DoNotDisturb 1.0 1.0
唤醒词WakeWord 1.0 1.0
视觉焦点VisualActivityTracker 1.0 1.0
音频焦点AudioActivityTracker 1.0 1.0
设置Settings 1.0 1.0
系统System 1.1 1.0, 1.1
云端配置Configuration 1.0 1.0
红外控制 通过主控设备红外模块控制传统家电 1.0 1.0
自定义CustomApp 1.0 1.0

注意

如果设备从未调用过上报设备能力API,则所有必填的设备能力版本会设置为1.0可选的设备能力将默认不可用

请求

Method:PUT

URI:https://api.iflyos.cn/v1/devices/capabilities

Data:JSON

请求头

参数 说明 类型 必填
Content-Type 固定值,application/json String
Authorization 设备获取到的AccessToken,前面必须加上 Unknown macro: {Bearer} String

请求头样例

Content-Type: application/json

Authorization: Bearer {{IVS_ACCESS_TOKEN}}

请求参数

参数 说明 类型 必填
envelopeVersion 这个值与调用【IVS】的接口版本保持一致,固定值:v20180810 String
capabilities 设备能力列表,必须是所有你能支持的设备能力列表 list
capabilities.type 固定值,iFLYOS.Interface String
capabilities.interface 设备能力名称,如:AudioPlayer String
capabilities.version 设备能力版本号,注意:每个设备能力都有独立的版本号,不同的版本对应的playload也会不同 String

请求体示例

以下只是一个示例,当调用接口时,务必将设备支持的所有设备能力完整的上报。

{
  "envelopeVersion": "v20180810",
  "capabilities": [
    {
      "type": "iFLYOS.Interface",
      "interface": "Alerts",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "AudioPlayer",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "PlaybackController",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "Settings",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "Speaker",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "SpeechRecognizer",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "SpeechSynthesizer",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "System",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "TemplateRuntime",
      "version": "1.0"
    },
    {
      "type": "iFLYOS.Interface",
      "interface": "CustomApp",
      "version": "1.0"
    }
  ]
}

响应

通过响应HTTP状态码来判断结果

状态码 说明
204 处理成功,返回内容为空
400 参数出错,返回json格式的错误信息
401 认证失败,或没有权限
500 内部错误,不返回信息。注意:设备在1秒后重试,重试间隔以指数方式增加(2、4、8、16、32...)直到256秒, 重试间隔保持在最大256秒,一直重试直到返回204

错误信息

响应状态码为400时,会返回一个包含错误信息的json对象

错误信息示例:

{ "error": { "message": "xxxxxxxx" } }
错误信息 描述 示例
不合法的envelop_version 请求body中envelop_version中的值不正确 不合法的envelop_version
capabilities列表不存在 请求body中capabilities列表不存在 capabilities列表不存在
未知的interface: {interface}, type: {type}, version: {version}组合 请求body的capabilities列表中,某个对象的type, interface, version字段组合不符合要求 未知的interface: MyTemplate, type: MY.interface, version: 0.1组合
XXXX为必填设备能力,请补充 请求body中capabilities列表遗漏某些必填设备能力 Alerts为必填设备能力,请补充