更新时间:2023-04-13 GMT+08:00
分享

创建软件升级任务

接口说明

若需要对设备进行软件版本升级,应用服务器可调用此接口为多个设备创建软件升级任务,升级前请确保目标版本包已上传到物联网平台。

注意事项

仅支持对使用LWM2M协议接入的设备进行软件升级。

URI

请求方法

POST

URI

/iodm/northbound/v1.5.0/operations/softwareUpgrade

传输协议

HTTPS

请求参数

参数

必选/可选

类型

位置

描述

app_key

必选

String

header

访问物联网平台的应用ID,在物联网平台创建应用时由平台分配获得。

Authorization

必选

String

header

访问物联网平台的认证信息,值为“Bearer {accessToken}”,其中{accessToken}为调用鉴权接口返回的accessToken。

fileId

必选

String

body

要升级的目标版本包ID。

targets

必选

OperateDevices

body

要进行升级的目标。

policy

可选

OperatePolicy

body

升级任务的执行策略。

OperateDevices:

参数

必选/可选

类型

位置

描述

deviceGroups

可选

List<String>

body

设备组名称列表,最多支持256个设备组。

与指定设备列表方式二选一。

deviceType

可选

String(256)

body

设备类型。

指定设备组时,此字段必选。

model

可选

String(256)

body

设备型号。

指定设备组时,此字段必选。

manufacturerName

可选

String(256)

body

设备厂商名称。

指定设备组时,此字段必选。

devices

可选

List<String>

body

设备ID列表,最多支持256个设备。

与指定设备组方式二选一。

OperatePolicy:

参数

必选/可选

类型

位置

描述

executeType

必选

String

body

执行类型,默认值为now。

  • now:现在执行
  • device_online:设备上线时执行
  • custom:自定义

startTime

可选

String

body

任务执行时间,executeType为custom时必选,需要填写UTC时间,格式:yyyyMMdd'T'HHmmss'Z',如 20151212T121212Z。

您需要根据本地所在时区自己进行时间转换。

endTime

可选

String

body

任务停止时间,executeType为custom时必选,需要填写UTC时间,格式:yyyyMMdd'T'HHmmss'Z',如 20151212T121212Z。

您需要根据本地所在时区自己进行时间转换。

retryType

可选

Boolean

body

执行失败是否进行重试,默认不重试。

  • true:重试
  • false:不重试

retryTimes

可选

Integer[1,5]

body

重试次数, 取值范围1-5,retryType为true时必选。

响应参数

Status Code: 200ok

参数

类型

描述

operationId

String

操作任务ID。

请求示例

POST https://{host}:{port}/iodm/northbound/v1.5.0/operations/softwareUpgrade
Content-Type: application/json
app_key: ******
Authorization: Bearer ******

{
  "fileId": "**********",
  "targets": {
    "devices": [
      "*****"
    ]
  }
}

正常响应示例

Status Code: 200 OK
Content-Type: application/json

{
  "operationId": "**********"
}

错误码

Http状态码

错误码

错误描述

说明

400

120015

Bad request error.

请求错误。

处理建议:请检查请求参数的是否有误。

400

123016

The parameter is error, targetversion not match with device.

参数不正确,目标版本与指定设备不匹配。

处理建议:请检查接口请求中deviceType、manufacturerName、model,与参数fileId指定的目标版本包信息是否一致。

400

123019

manufacturerName is null.

厂商名称内容为空。

处理建议:请检查接口请求中的manufacturerName是否为空。

400

123020

deviceType is null

设备类型内容为空。

处理建议:请检查接口请求中的deviceType是否为空。

400

123021

model is null.

设备型号内容为空。

处理建议:请检查接口请求中的model是否为空。

400

123022

deviceGroups and devices cannot be null together

deviceGroups和devices不能同时为空。

处理建议:deviceGroups与devices必须要选择一个进行赋值。

400

123023

deviceGroups and devices cannot be exist together

deviceGroups和devices不能同时存在。

处理建议:deviceGroups与devices只能选择一个进行赋值。

400

123024

The number of deviceGroups or devices reached upper limit

deviceGroups或devices内容数量达到上限。

处理建议:请检查deviceGroups或devices的内容,数量不能超过256个。

400

123025

executeType is error or can not to be null.

executeType有误或不能为空。

处理建议:请检查接口请求中的executeType是否为空或者是否有误。

400

123026

startTime or endTime is null or error.

startTime或endTime为空或有误。

处理建议:请检查接口请求中的startTime和endTime是否为空或者格式有误。

400

123028

retryTimes is null or beyond the limit.

retryTimes为空或超出上限。

处理建议:请检查接口请求中的retryTimes是否为空,或者不能小于1或者大于5。

400

123032

startTime can not be later than the endTime.

startTime的时间不能比endTime晚。

处理建议:请检查接口请求中的startTime是否晚于endTime。

400

123033

startTime can not be earlier than the now.

startTime的时间不能比当前时间早。

处理建议:请检查接口请求中的startTime是否早于当前时间。

400

123034

endtime must be greater than 5 minutes.

endtime要比startTime大5分钟。

处理建议:请检查接口请求中的startTime和endTime间隔时间必须大于5分钟。

403

1010009

app throttle exceed.

应用调用接口过于频繁,超过流控值(默认值是100次/60s)。

处理建议:联系物联网平台维护人员调大流控阈值或者控制接口的调用频率。

403

1010005

Invalid access token or appId.

错误的token信息。

处理建议:请检查接口请求中所携带的accessToken是否有误。

404

123002

Device or package file not found.

设备或包不存在

处理建议:请检查接口请求中的fileId是否正确。

相关文档