V2.1 Get OTA Job¶

Get the details of an OTA job.

This API is available in EnOS 2.2.0 and above.

If you need to invoke this API after performing bulk updates to relevant OTA jobs using other APIs, it is recommended to wait for about 2 seconds to avoid obtaining unupdated data.

Operation Permissions¶

Before invoking this API, ensure that the service account has been authorized the policy that includes the following service(s) and action permission(s). For how to authorize the service account, see Managing Service Accounts.

Required Service	Required Operation Permission
Firmware	Read OTA

Request Format¶

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

Request Parameters (URI)¶

Name	Location (Path/Query)	Mandatory/Optional	Data Type	Description
orgId	Query	Mandatory	String	The organization ID which the asset belongs to. How to get orgId>>
jobId	Query	Mandatory	String	The OTA job ID.

Response Parameters¶

Note

For old firmware files, return product information. For new firmware files, do not return product information.

Name	Data Type	Description
data	JobInfo Struct	The details of the OTA job. For more information, see JobInfo Struct.

JobInfo Struct ¶

Name	Data Type	Description
orgId	String	The organization ID.
productKey	String	The product key.
jobId	String	The OTA job ID.
name	StringI18n	The job name.
firmwareId	String	The firmware ID.
firmwareVersion	String	The firmware version.
firmwareName	StringI18n	The firmware name.
type	String	The job type, `verify` or `upgrade`.
enableUpgradeRequest	Boolean	`true`: Device can request for upgrade. `false`: Device cannot request for upgrade.
upgradePolicy	String	The upgrade policy, `snapshot` or `incremental`.
upgradeScope	UpgradeScope Struct	The scope of the upgrade. For more details, see UpgradeScope Struct.
upgradeTimeout	Long	The timeout in seconds for the upgrade/verification, which starts when the OTA task enters the “upgrading” state. You can use the Search OTA Task API to search for the status of the OTA task.
retryPolicy	RetryPolicy Struct	The policy for retrying failed OTA tasks. For more details, see RetryPolicy Struct.
schedulePolicy	SchedulePolicy Struct	The schedule policy for the OTA task. For more details, see SchedulePolicy Struct.
maximumConcurrency	Integer	The maximum number of concurrent upgrade tasks.
status	String	The status of the job, `started` or `stopped`.
createTime	Long	The time when the OTA job was created.

UpgradeScope Struct ¶

Name	Data Type	Description
type	String	The scope of the devices to be upgraded. Available values are as per the below. `total`: Upgrade all devices whose firmware version number matches what is specified in `versionNumbers`. `partial`: Out of all the devices whose firmware version number matches what is specified in `versionNumbers`, only upgrade/verify some of them. Firmware upgrade uses the `deviceKeys`, `attributes`, `tags`, or `assetTrees` parameters in this struct while firmware verification only uses `deviceKeys`.
versionNumbers	String Array	The list of firmware version numbers.
deviceKeys	String Array	The devices for firmware upgrade or verification via device keys. Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` will be used to specify the device.
attributes	Map (Key is of String type, and Value is of Object Array)	The devices for firmware upgrade or verification via the attributes and their corresponding values. Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` will be used to specify the device.
tags	Map (Key is of String type, and Value is of String Array)	The devices for firmware upgrade or verification via the device tags and their corresponding values. Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` will be used to specify the device.
assetTrees	AssetTreeScope Struct	The devices for firmware upgrade or verification via asset tree. Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` will be used to specify the device. For more details, see AssetTreeScope Struct.

AssetTreeScope Struct ¶

Name	Data Type	Description
treeId	String	The asset tree ID.
includedNodes	String Array	The nodes in the asset tree, identified by the asset’s asset ID. Specifying one node means all sub-nodes are included as well. If this is blank, the entire tree is selected.

RetryPolicy Struct ¶

Name	Data Type	Description
enableRetry	Boolean	`true`: Able to retry task if task fails `false`: Not able to retry task if task fails
retryInterval	Integer	The retry interval in seconds after failure if `enableRetry` is `true`.
retryCount	Integer	The maximum number of retries if `enableRetry` is `true`.

SchedulePolicy Struct ¶

Name	Data Type	Description
isRepeatDaily	Boolean	`true`: The task will repeat daily. `false`: The task will not repeat daily.
startTimestamp	Long	The timestamp of the schedule start time.
endTimestamp	Long	The timestamp of the schedule end time.
timezoneOffsetInMinutes	Integer	Timezone offset in minutes.

Error Codes¶

Code	Message	Description
24404	Job not found	The job cannot be found.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.1/ota-jobs?action=get&orgId=yourOrgId&jobId=yourJobId
method: GET

Return Sample¶

{
    "code":0,
    "msg":"OK",
    "requestId":"42fc4dcd-636b-48ac-a69b-4d2f95d0c3de",
    "data":{
        "orgId":"yourOrgId",
        "productKey":"yourProductKey",
        "jobId":"yourJobId",
        "name":{
            "defaultValue":"name",
            "i18nValue":{

            }
        },
        "firmwareId":"5ed0dd4a646542001b3d113f",
        "type":"upgrade",
        "enableUpgradeRequest":true,
        "upgradePolicy":null,
        "upgradeScope":{
            "type":"total",
            "versionNumbers":[
                "1.0"
            ],
            "deviceKeys":null,
            "attributes":null,
            "tags":null,
            "assetTrees":null
        },
        "startSchedule":null, //deprecated
        "endSchedule":null, //deprecated
        "status":"started",
        "createTime":1591171274788
    }
}

SDK Samples¶

You can access the SDK samples for Connection Service on GitHub:

Java
Python