Create OTA Job¶
创建批量的固件 OTA 验证或升级任务。
操作权限¶
需授权的资源 | 所需操作权限 |
---|---|
设备管理 | Full Access |
请求格式¶
POST https://{apigw-address}/connect-service/v2.1/ota-jobs?action=create
请求参数(URI)¶
名称 | 位置(Path/Query) | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|---|
orgId | Query | 必需 | String | 资产所属的组织 ID。如何获取orgId信息>> |
firmwareId | Query | 必需 | String | 需要升级到的目标固件 ID。 |
请求参数(Body)¶
根据创建的是验证任务还是固件升级任务,请求参数(Body)的结构也会不同:
升级任务¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
name | 可选 | StringI18n | 任务名称。参见 国际化名称结构体>> |
type | 必需 | String | 任务类型,有以下可选值:
|
upgradeScope | 必需 | UpgradeScope 结构体 | 待升级的设备及版本号等信息,其结构见 UpgradeScope结构体>> |
upgradePolicy | 必需 | String | 升级策略,有以下可选值:
其含义参见 升级策略>> |
enableUpgradeRequest | 必需 | Boolean | 是否允许设备主动请求升级。 |
upgradeTimeout | 可选 | Long | 升级超时时间,当 OTA task 进入 upgrading 状态时开始计算。范围为 300 到 172800,默认值为 7200 秒。你可以使用 Search OTA Task 来查询 OTA task 的状态。 |
retryPolicy | 可选 | RetryPolicy 结构体 | 失败 OTA 任务重试的策略,如为空,则默认不重试。其结构见 RetryPolicy 结构体>> |
schedulePolicy | 可选 | SchedulePolicy 结构体 | OTA 任务调度的策略,如为空,则默认调度任务立刻开始执行,执行时间为 00:00:00 到 23:59:59,每日重复。其结构见 SchedulePolicy 结构体>> |
maximumConcurrency | 可选 | Integer | 升级任务最大并发量。默认值 300。 |
固件验证任务¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
name | 可选 | StringI18n | 任务名称。参见 国际化名称结构体>> |
type | 必需 | String | 任务类型,有以下可选值
|
upgradeScope | 必需 | UpgradeScope 结构体 | 待升级的设备及版本号等信息,其结构见 UpgradeScope 结构体>> 。对于固件验证任务,该结构体中的 type 参数的值必需为 partial 。 |
upgradeTimeout | 可选 | Long | 升级任务超时时间,当 task 进入 published 状态时开始计算,默认 7200 秒,范围 300 到 172800。有关 OTA task 的升级状态,参见 Search OTA Task>> |
UpgradeScope 结构体 ¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
type | 必需 | String | 待升级设备的范围。有以下可选值:
|
versionNumbers | 必需 | String 数组 | 待升级的固件版本号列表。 |
deviceKeys | 可选 | String 数组 | 指定固件待验证或升级的设备的 Device Key。只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备。 |
attributes | 可选 | Map(Key 为 String,Value 为 Object 数组) | 指定具有特定属性和属性值的设备加入固件验证或升级。只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备。 |
tags | 可选 | Map(Key 为 String,Value 为 String 数组) | 指定具有特定标签和标签值的设备加入固件验证或升级。只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备。 |
assetTrees | 可选 | AssetTreeScope 结构体 | 指定资产树里的设备加入固件验证或升级。只能通过 deviceKeys attributes tags assetTrees 其中一个参数来指定设备。 其结构见 AssetTreeScope Struct>> |
AssetTreeScope 结构体 ¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
treeId | 必需 | String | 资产树 ID。 |
includedNotes | 可选 | String Array | 资产树中的节点。选择一个节点代表其自身及所有子节点,不填代表选择整棵树。 |
RetryPolicy 结构体 ¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
enableRetry | 可选 | Boolean |
|
retryInterval | enableRetry 为 true 时必填 |
Integer | 失败后自动重试间隔时间 |
retryCount | enableRetry 为 true 时必填 |
Integer | 最大自动重试次数 |
SchedulePolicy 结构体 ¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
isRepeatDaily | 可选 | Boolean |
|
startTimestamp | 必需 | Long | 开始调度时间的 13 位时间戳 |
endTimestamp | 必需 | Long | 结束调度时间的 13 位时间戳。如果 isRepeatDaily 为 true ,则需要和 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"
}
}
Java SDK 调用示例¶
package com.envisioniot.enos.connect_service.ota.job;
import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.api.common.constant.common.StringI18n;
import com.envisioniot.enos.connect_service.v2_1.ota.job.CreateJobRequest;
import com.envisioniot.enos.connect_service.v2_1.ota.job.CreateJobResponse;
import com.envisioniot.enos.connect_service.vo.ota.UpgradeScope;
import com.google.common.collect.ImmutableSet;
public class CreateJob {
public static void main(String[] args) {
final String appKey = "yourAppKey";
final String appSecret = "yourAppSecret";
String serverUrl = "yourServerUrl";
String orgId = "yourOrgId";
String firmwareId = "yourFirmwareId";
CreateJobRequest request = new CreateJobRequest();
request.setOrgId(orgId);
request.setFirmwareId(firmwareId);
request.setName(new StringI18n("testJob"));
request.setType("upgrade");
request.setUpgradePolicy("snapshot");
// Instantiate upgradeScope
UpgradeScope upgradeScope = new UpgradeScope();
upgradeScope.setType("partial");
// versionNumbers is required, whatever the type.
upgradeScope.setVersionNumbers(ImmutableSet.of("1.0"));
// Define your filter if type is "partial"
upgradeScope.setDeviceKeys(ImmutableSet.of("deviceKey1","deviceKey2"));
request.setUpgradeScope(upgradeScope);
request.setEnableUpgradeRequest(true);
request.setStartSchedule(0L);
request.setEndSchedule(2000L);
CreateJobResponse response = Poseidon
.config(PConfig.init().appKey(appKey).appSecret(appSecret).debug())
.url(serverUrl)
.getResponse(request, CreateJobResponse.class);
}
}