固件升级服务
更新时间:2018-05-18 12:08:39
提供一组与OTA固件升级相关的配套服务接口,客户端应用通过本组接口可以获取指定设备的固件信息以及固件升级状态,同时提供了固件升级确认接口(当固件升级需要用户许可时使用)。
获取固件升级信息
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/progress/getByUser | 1.0.2 | 获取某一个设备的固件升级信息,需要指定具体的固件版本号。如果存在相应的固件,返回当前固件的升级进度等信息。 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iotId | String | 是 | 设备id |
version | String | 是 | 对应的固件版本号 |
返回参数
字段名
|
字段类型
|
必有
|
详细描述
|
iotId
|
String
|
是
|
设备id
|
step
|
Integer
|
是
|
升级进度(当为负数时,表示升级错误信息,非负数时为升级进度百分比)
升级错误信息定义如下:
-1:升级操作失败
-2:固件文件下载失败
-3:固件文件校验失败
-4:固件文件烧写失败
|
desc
|
String
|
否
|
描述信息
|
success
|
Boolean
|
是
|
是否成功标记,当为true时表示固件升级操作成功,反之表示升级未完成(可能正在升级或升级失败),请优先选择upgradeStatus参数来判断固件升级状态
|
needConfirm
|
Boolean
|
是
|
是否需要用户进行确认操作
|
upgradeStatus
|
Integer
|
是
|
当前升级状态
0:待升级/待确认
1:升级中
2:升级异常
3:升级失败
4:升级成功
|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
"iotId": "",
"version": "1.0.1"
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200,
"data": {
"iotId": "xxxx",
"step": 10,
"desc": "xxxxxx",
"success": false,
"needConfirm": true,
"upgradeStatus": 0
}
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9112 | there is no device exist | 业务 | 设备不存在 |
9119 | firmware not exist | 业务 | 固件不存在 |
9146 | upgrade record not exist | 业务 | 升级记录不存在 |
获取设备固件
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/info/queryByUser | 1.0.2 | 获取某一个设备当前的升级固件信息 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iotId | String | 是 | 设备id |
返回参数
字段名
|
字段类型
|
必有
|
详细描述
|
currentVersion
|
String
|
是
|
当前设备实际烧录的版本号
|
version
|
String
|
是
|
待升级设备的目标版本号,如果目标版本号比实际烧录固件版本号低,则返回的是当前设备实际烧录的版本号
|
currentTimestamp
|
Date
|
否
|
设备当前烧录的固件,对应的文件上传到云端时记录的时间
|
timestamp
|
Date
|
是
|
设备当前最新固件文件上传到云端时记录的时间
|
size
|
String
|
是
|
文件包大小,单位Byte
|
md5
|
String
|
是
|
版本固件文件md5
|
name
|
String
|
是
|
版本固件名称
|
url
|
String
|
是
|
版本固件地址,sts加密
|
desc
|
String
|
否
|
版本详情描述
|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
"iotId": "xxxxx"
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200,
"data": {
"currentVersion": "1.2.2",
"version": "1.2.3",
"currentTimestamp": "2017-09-08 16:08:08",
"timestamp": "2017-09-10 12:11:34",
"size": "4000000",
"md5": "xxxxxxx",
"name": "xxxxxxx",
"url": "xxxxxxx",
"desc": "xxxxxxx"
}
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9112 | there is no device exist | 业务 | 设备不存在 |
9119 | firmware not exist | 业务 | 固件不存在 |
9132 | non-existent job record | 业务 | 升级任务记录不存在 |
取消固件升级
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/unupgradeByUser | 1.0.2 | 取消某一个设备的固件升级流程 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
version | String | 是 | 对应的固件版本号 |
iotId | String | 是 | 设备id |
返回参数
字段名
|
字段类型
|
必有
|
详细描述
|
data
|
Boolean
|
是
|
取消操作指令处理是否成功
True:成功
False:失败
|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
"iotId": "xxxxxxx",
"version": "1.0.1"
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200,
"data": "true"
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9112 | there is no device exist | 业务 | 设备不存在 |
9119 | firmware not exist | 业务 | 固件不存在 |
9132 | non-existent job record | 业务 | 升级任务记录不存在 |
触发固件升级
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/upgradeByUser | 1.0.2 | 触发启动某一个设备的固件升级动作 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
version | String | 是 | 对应的固件版本号 |
iotId | String | 是 | 设备id |
返回参数
字段名
|
字段类型
|
必有
|
详细描述
|
currentVersion
|
String
|
是
|
当前设备实际烧录的版本号
|
version
|
String
|
是
|
待升级设备的目标版本号,如果目标版本号比实际烧录固件版本号低,则返回的是当前设备实际烧录的版本号
|
currentTimestamp
|
Date
|
否
|
设备当前烧录的固件,对应的文件上传到云端时记录的时间
|
timestamp
|
Date
|
是
|
设备当前最新固件文件上传到云端时记录的时间
|
size
|
String
|
是
|
文件包大小,单位Byte
|
md5
|
String
|
是
|
版本固件文件md5
|
name
|
String
|
是
|
版本固件名称
|
url
|
String
|
是
|
版本固件地址,sts加密
|
desc
|
String
|
否
|
版本详情描述
|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
"iotId": "xxxxxxx",
"version": "1.0.1"
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200,
"data": {
"currentVersion": "1.2.2",
"version": "1.2.3",
"currentTimestamp": "2017-09-08 16:08:08",
"timestamp": "2017-09-10 12:11:34",
"size": "4000000",
"md5": "xxxxxxx",
"name": "xxxxxxx",
"url": "xxxxxxx",
"desc": "xxxxxxx"
}
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9103 | update data failed | 业务 | 升级失败 |
9112 | there is no device exist | 业务 | 设备不存在 |
9132 | non-existent job record | 业务 | 升级任务记录不存在 |
获取正在升级的设备列表
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/upgrade/listByUser | 1.0.2 | 获取当前正在升级的设备列表信息 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
返回参数
字段名 | 字段类型 | 必有 | 详细描述 |
---|---|---|---|
data | List | 无 | 当前正在升级的设备信息列表 |
列表结构
字段名
|
字段类型
|
必有
|
详细描述
|
iotId
|
String
|
是
|
设备id
|
step
|
Integer
|
是
|
升级进度(当为负数时,表示升级错误信息,非负数时为升级进度百分比)
升级错误信息定义如下:
-1:升级操作失败
-2:固件文件下载失败
-3:固件文件校验失败
-4:固件文件烧写失败
|
desc
|
String
|
否
|
描述信息
|
success
|
Boolean
|
是
|
是否成功标记,当为true时表示固件升级操作成功,反之表示升级未完成(可能正在升级或升级失败),请优先选择upgradeStatus参数来判断固件升级状态
|
needConfirm
|
Boolean
|
是
|
是否需要用户进行确认操作
|
upgradeStatus
|
Integer
|
是
|
当前升级状态
0:待升级/待确认
1:升级中
2:升级异常
3:升级失败
4:升级成功
|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200,
"data": [
{
"iotId": "xxxx",
"step": 10,
"desc": "xxxxxx",
"success": false,
"needConfirm": true,
"upgradeStatus": 0
},
{
"iotId": "xxxx",
"step": 10,
"desc": "xxxxxx",
"success": false,
"needConfirm": true,
"upgradeStatus": 0
}
]
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9131 | invalid device | 业务 | 非法的设备 |
9144 | device count exceeded | 业务 | 设备数量超限 |
上报固件升级进度
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/ota/progress/postByUser | 1.0.2 | 上报某一个设备的固件升级的进度信息给到云端进行记录 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iotId | String | 是 | 设备id |
step | String | 是 | 固件升级进度信息(百分比) |
desc | String | 是 | 升级信息的描述 |
version | String | 是 | 对应的固件版本号信息 |
返回参数
字段名 | 字段类型 | 必有 | 详细描述 |
---|---|---|---|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
"iotId": "xxxx",
"step": "1",
"desc": "xxxx",
"version": "1.0.1"
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9112 | there is no device exist | 业务 | 设备不存在 |
9143 | upgrade info posted is invalid | 业务 | 升级进度上报错误 |
上报版本号
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/version/reportByUser | 1.0.2 | 上报某一个设备当前烧录的版本号信息给云端 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iotId | String | 是 | 设备id |
version | String | 是 | 固件版本号 |
返回参数
字段名 | 字段类型 | 必有 | 详细描述 |
---|---|---|---|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
"iotId": "xxxx",
"version": "1.0.1"
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9112 | there is no device exist | 业务 | 设备不存在 |
9153 | evice auth failed | 业务 | 设备校验失败 |
批量升级(确认)设备
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/batchUpgradeByUser | 1.0.1 | 批量确认设备进入升级状态,用于需要客户端进行人为确认方可进行升级的场景 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iotIds | List |
是 | 设备id信息列表 |
返回参数
字段名 | 字段类型 | 必有 | 详细描述 |
---|---|---|---|
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
"iotIds": ["iotid1","iotid2"]
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |
9112 | there is no device exist | 业务 | 设备不存在 |
获取待升级的设备列表
定义描述
path | 版本 | 描述 | 是否需要登陆 |
---|---|---|---|
/thing/ota/listByUser | 1.0.2 | 获取当前用户名下的待升级(待确认)的设备列表 | 是 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
返回参数
字段名 | 字段类型 | 必有 | 详细描述 |
---|---|---|---|
data | List | 无 | 当前用户名下的待升级(待确认)的设备列表 |
列表结构
字段名 | 字段类型 | 必有 | 详细描述 |
---|---|---|---|
iotId | String | 是 | 设备id |
image | String | 否 | 设备对应的品类图标,当云端系统配置了设备所属产品的品类图标时有效 |
deviceName | String | 否 | 设备显示名称,会优先使用用户配置的设备昵称返回,如果不存在昵称的配置则返回对应的产品名称 |
示例
请求示例
{
"id": "1509086454180",
"version": "1.0",
"request": {
"apiVer": "1.0.2",
"iotToken": "token"
},
"params": {
}
}
正常返回示例
{
"id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
"code": 200,
"data": [
{
"iotId": "xxxx",
"image": "xxxx",
"deviceName": "xxxxxx"
},
{
"iotId": "xxxx",
"image": "xxxx",
"deviceName": "xxxxxx"
}
]
}
错误码
错误码 | 错误信息 | 来源 | 描述 |
---|---|---|---|
200 | success | 系统 | 成功 |
400 | request error. | 系统 | 请求错误 |
401 | request auth error. | 系统 | 请求认证错误 |
403 | request forbidden. | 系统 | 请求被禁止 |
404 | service not found. | 系统 | 服务未找到 |
429 | too many requests. | 系统 | 太多请求 |
460 | request parameter error. | 系统 | 请求参数错误 |
500 | service error. | 系统 | 服务端错误 |
503 | service not available. | 系统 | 服务不可用 |