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 |
任务类型,有以下可选值:
|
upgradeScope |
必需 |
UpgradeScope 结构体 |
待升级的设备及版本号等信息,其结构参见 UpgradeScope 结构体。 |
upgradePolicy |
必需 |
String |
升级策略,升级任务使用 其含义参见 升级策略。 |
enableUpgradeRequest |
必需 |
Boolean |
是否允许设备主动请求升级。 |
upgradeTimeout |
可选 |
Long |
升级超时时间,当 OTA task 进入 |
retryPolicy |
可选 |
RetryPolicy 结构体 |
失败 OTA 任务重试的策略,如为空,则默认不重试。其结构参见 RetryPolicy 结构体。 |
schedulePolicy |
可选 |
SchedulePolicy 结构体 |
OTA 任务调度的策略,如为空,则默认调度任务立刻开始执行,执行时间为 00:00:00 到 23:59:59,每日重复。其结构参见 SchedulePolicy 结构体。 |
maximumConcurrency |
可选 |
Integer |
升级任务最大并发量。默认值 300。 |
固件验证任务¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
type |
必需 |
String |
任务类型,验证任务使用 |
upgradeScope |
必需 |
UpgradeScope 结构体 |
待升级的设备及版本号等信息,其结构参见 UpgradeScope 结构体。对于固件验证任务,该结构体中的 |
upgradeTimeout |
可选 |
Long |
升级任务超时时间,当 task 进入 published 状态时开始计算,默认 7200 秒,范围 300 到 172800。有关 OTA task 的升级状态,参见 Search OTA Task。 |
UpgradeScope 结构体 ¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
type |
必需 |
String |
待升级设备的范围。有以下可选值:
|
versionNumbers |
必需 |
String 数组 |
待升级的固件版本号列表。 |
deviceKeys |
可选 |
String 数组 |
指定固件待验证或升级的设备的 Device Key。固件升级只能通过 |
attributes |
可选 |
Map(Key 为 String,Value 为 Object 数组) |
指定具有特定属性和属性值的设备加入固件验证或升级。固件升级只能通过 |
tags |
可选 |
Map(Key 为 String,Value 为 String 数组) |
指定具有特定标签和标签值的设备加入固件验证或升级。固件升级只能通过 |
assetTrees |
可选 |
AssetTreeScope 结构体 |
指定资产树(最多 5 棵资产树)里的设备加入固件验证或升级。固件升级只能通过 |
AssetTreeScope 结构体 ¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
treeId |
必需 |
String |
资产树 ID。 |
includedNodes |
可选 |
String Array |
资产树中的节点,由资产的 asset ID 识别。选择一个节点代表其自身及所有子节点,不填代表选择整棵树。 |
RetryPolicy 结构体 ¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
enableRetry |
可选 |
Boolean |
|
retryInterval |
|
Integer |
失败后自动重试间隔时间(秒)。范围:0 ~ 86400 |
retryCount |
|
Integer |
最大自动重试次数。范围:1 ~ 5 |
SchedulePolicy 结构体 ¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
isRepeatDaily |
可选 |
Boolean |
|
startTimestamp |
必需 |
Long |
开始调度时间的 13 位时间戳。 |
endTimestamp |
必需 |
Long |
结束调度时间的 13 位时间戳。如果 |
响应参数¶
名称 |
数据类型 |
描述 |
---|---|---|
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,因为固件启用 |
24611 |
upgradeScope type total is not allowed for verification task |
验证任务不能使用在 |
24612 |
Exceeded max verification deviceKeys, max[%d] |
验证任务超过了允许的最大 |
示例¶
请求示例¶
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 示例: