# 设备能力API

报告设备能力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	是

请求体示例

TIP

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

{
  "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为必填设备能力，请补充