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 |
|
| 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.
|
| 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 |
|
| 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 |
|
| 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
}
}