V2.1 Create OTA Job


创建批量的固件 OTA 验证或升级任务。

该 API 支持在 EnOS 2.2.0 及以上环境中使用。

操作权限


使用此 API 前,确保服务账号已被授予包含下列服务和操作权限的策略。有关授权服务账号的更多信息,参见 管理服务账号


需授权的服务

所需操作权限

固件

Create OTA

前提条件


  • 确保已创建所需设备和固件。

  • 确保已阅读固件升级相关的 使用限制

请求格式

POST https://{apigw-address}/connect-service/v2.1/ota-jobs?action=create

请求参数(URI)

名称

位置(Path/Query)

必需/可选

数据类型

描述

orgId

Query

必需

String

资产所属的组织 ID。如何获取 orgId 信息>>

firmwareId

Query

必需

String

需要升级到的目标固件 ID。前往 OTA 升级 > 固件管理固件ID 列查看固件ID。

请求参数(Body)

根据创建的是验证任务还是固件升级任务,请求参数(Body)的结构也会不同:

升级任务

名称

必需/可选

数据类型

描述

name

可选

StringI18n

任务名称。其结构参见 国际化名称结构体

type

必需

String

任务类型,有以下可选值:

  • verify: 验证任务

  • upgrade: 升级任务

upgradeScope

必需

UpgradeScope 结构体

待升级的设备及版本号等信息,其结构参见 UpgradeScope 结构体

upgradePolicy

必需

String

升级策略,升级任务使用 upgrade

其含义参见 升级策略

enableUpgradeRequest

必需

Boolean

是否允许设备主动请求升级。

upgradeTimeout

可选

Long

升级超时时间,当 OTA task 进入 upgrading 状态时开始计算。范围为 300 到 172800,默认值为 7200 秒。OTA task 的状态可以使用 Search OTA Task 来查询。

retryPolicy

可选

RetryPolicy 结构体

失败 OTA 任务重试的策略,如为空,则默认不重试。其结构参见 RetryPolicy 结构体

schedulePolicy

可选

SchedulePolicy 结构体

OTA 任务调度的策略,如为空,则默认调度任务立刻开始执行,执行时间为 00:00:00 到 23:59:59,每日重复。其结构参见 SchedulePolicy 结构体

maximumConcurrency

可选

Integer

升级任务最大并发量。默认值 300。

固件验证任务

名称

必需/可选

数据类型

描述

type

必需

String

任务类型,验证任务使用 verify

upgradeScope

必需

UpgradeScope 结构体

待升级的设备及版本号等信息,其结构参见 UpgradeScope 结构体。对于固件验证任务,该结构体中的 type 参数的值必需为 partial

upgradeTimeout

可选

Long

升级任务超时时间,当 task 进入 published 状态时开始计算,默认 7200 秒,范围 300 到 172800。有关 OTA task 的升级状态,参见 Search OTA Task

UpgradeScope 结构体

名称

必需/可选

数据类型

描述

type

必需

String

待升级设备的范围。有以下可选值:

  • total : 所有的固件版本号为 versionNumbers 中指定的版本号的设备

  • partial : 固件版本号为 versionNumbers 中指定的版本号的设备的其中一部分。对于 升级任务,可以通过结构体内的 deviceKeys attributes tags assetTrees 中的某一个参数来具体指定升级哪些设备,固件验证任务 则只能通过 deviceKeys 指定验证哪些设备。

versionNumbers

必需

String 数组

待升级的固件版本号列表。

deviceKeys

可选

String 数组

指定固件待验证或升级的设备的 Device Key。固件升级只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备,固件验证则只能通过 deviceKeys 来指定设备。

attributes

可选

Map(Key 为 String,Value 为 Object 数组)

指定具有特定属性和属性值的设备加入固件验证或升级。固件升级只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备,固件验证则只能通过 deviceKeys 来指定设备。

tags

可选

Map(Key 为 String,Value 为 String 数组)

指定具有特定标签和标签值的设备加入固件验证或升级。固件升级只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备,固件验证则只能通过 deviceKeys 来指定设备。

assetTrees

可选

AssetTreeScope 结构体

指定资产树(最多 5 棵资产树)里的设备加入固件验证或升级。固件升级只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备,固件验证则只能通过 deviceKeys 来指定设备。其结构参见 AssetTreeScope 结构体

AssetTreeScope 结构体

名称

必需/可选

数据类型

描述

treeId

必需

String

资产树 ID。

includedNodes

可选

String Array

资产树中的节点,由资产的 asset ID 识别。选择一个节点代表其自身及所有子节点,不填代表选择整棵树。

RetryPolicy 结构体

名称

必需/可选

数据类型

描述

enableRetry

可选

Boolean

  • true:开启失败重试。

  • false:不开启失败重试,默认为 false

retryInterval

enableRetrytrue 时必填

Integer

失败后自动重试间隔时间(秒)。范围:0 ~ 86400

retryCount

enableRetrytrue 时必填

Integer

最大自动重试次数。范围:1 ~ 5

SchedulePolicy 结构体

名称

必需/可选

数据类型

描述

isRepeatDaily

可选

Boolean

  • true:任务每日重复。

  • false:任务不会每日重复,默认为 false

startTimestamp

必需

Long

开始调度时间的 13 位时间戳。

endTimestamp

必需

Long

结束调度时间的 13 位时间戳。如果 isRepeatDailytrue ,则需要和 startTimeStamp 在同一天。

响应参数

名称

数据类型

描述

data

JobCreateResult 结构体

固件验证或升级任务的创建结果。其结构参见 JobCreateResult 结构体

JobCreateResult 结构体

名称

数据类型

描述

jobId

String

任务 ID。

错误码

代码

错误信息

描述

24404

Firmware not found

找不到固件。

24610

Not allowed to create job as firmware is not verified while enable verification is switched on

无法创建 OTA job,因为固件启用 enableVerification 但尚未验证固件。

24611

upgradeScope type total is not allowed for verification task

验证任务不能使用在 UpgradeScope Struct 参数 type 里的 total 选项。

24612

Exceeded max verification deviceKeys, max[%d]

验证任务超过了允许的最大 deviceKeys 数。

示例

请求示例

url: https://{apigw-address}/connect-service/v2.1/ota-jobs?action=create&orgId=yourOrgId&firmwareId=yourFirmwareId
method: POST
requestBody:
{
    "name":{
        "defaultValue":"ota-job-test",
        "i18nValue":{

        }
    },
    "type":"upgrade",
    "upgradePolicy":"snapshot",
    "upgradeScope":{
        "type":"partial",
        "versionNumbers":[
            "1.0"
        ],
        "deviceKeys":[
            "deviceKey1",
            "deviceKey2"
        ]
    },
    "startSchedule":0,
    "endSchedule":86399,
    "enableUpgradeRequest":true
}

返回示例

{
    "code":0,
    "msg":"OK",
    "requestId":"0bdefc0f-369f-4664-a570-695f4e31877c",
    "data":{
        "jobId":"5ee1a91029b990001b9c188e"
    }
}

SDK 示例


你可以在 Github 上获取接入服务的 SDK 示例: