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 进入 |
retryPolicy |
可选 |
RetryPolicy 结构体 |
失败 OTA 任务重试的策略,如为空,则默认不重试。其结构见 RetryPolicy 结构体>> |
schedulePolicy |
可选 |
SchedulePolicy 结构体 |
OTA 任务调度的策略,如为空,则默认调度任务立刻开始执行,执行时间为 00:00:00 到 23:59:59,每日重复。其结构见 SchedulePolicy 结构体>> |
maximumConcurrency |
可选 |
Integer |
升级任务最大并发量。默认值 300。 |
固件验证任务¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
name |
可选 |
StringI18n |
任务名称。参见 国际化名称结构体>> |
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 结构体 |
指定资产树里的设备加入固件验证或升级。只能通过 |
AssetTreeScope 结构体 ¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
treeId |
必需 |
String |
资产树 ID。 |
includedNotes |
可选 |
String Array |
资产树中的节点。选择一个节点代表其自身及所有子节点,不填代表选择整棵树。 |
RetryPolicy 结构体 ¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
enableRetry |
可选 |
Boolean |
|
retryInterval |
|
Integer |
失败后自动重试间隔时间 |
retryCount |
|
Integer |
最大自动重试次数 |
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"
}
}
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);
}
}