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	任务类型，有以下可选值： `verify` : 验证任务 `upgrade` : 升级任务
upgradeScope	必需	UpgradeScope 结构体	待升级的设备及版本号等信息，其结构见 UpgradeScope结构体>>
upgradePolicy	必需	String	升级策略，有以下可选值： `snapshot` : 快照式升级 `incremental` : 增量式升级其含义参见升级策略>>
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	任务类型，有以下可选值 `verify` : 验证任务 `upgrade` : 升级任务
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` 中的某一个参数来具体指定是哪些设备被升级或验证。
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	`true`：开启失败重试。 `false`：不开启失败重试，默认为 `false`。
retryInterval	`enableRetry` 为 `true` 时必填	Integer	失败后自动重试间隔时间
retryCount	`enableRetry` 为 `true` 时必填	Integer	最大自动重试次数

SchedulePolicy 结构体 ¶

名称	必需/可选	数据类型	描述
isRepeatDaily	可选	Boolean	`true`：任务每日重复。 `false`：任务不会每日重复，默认为 `false`。
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);
    }
}