V2.1 Search OTA Job¶
Search for OTA jobs based on the search criteria.
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¶
POST https://{apigw-address}/connect-service/v2.1/ota-jobs?action=search
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>> |
Request Parameters (Body)¶
Name | Location (Path/Query) | Mandatory/Optional | Data Type |
---|---|---|---|
expression | Optional | String | The query expression, which supports sql-like query. The supported query fields are as per the below.
|
pagination | Optional | Pagination Request Struct | Lists the paging requirements in a request. When not specified, 10 records are displayed per page by default and sorted in descending order by createTime . The maximum records per page is 200 but for optimal performance, it is recommended to have not more than 50 records per page. sorters is not supported to sort the response. For more details, see Pagination Request Struct. |
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 |
---|---|---|
99400 | Do not allow operator op =, allowed op [like] | The syntax used in expression is not supported. |
For other error codes, see Common Error Codes.
Samples¶
Request Sample¶
url: https://{apigw-address}/connect-service/v2.1/ota-jobs?action=search&orgId=yourOrgId
method: POST
requestBody:
//example 1
{
"expression":"productKey='yourProductKey'",
"pagination":{
"pageNo":1,
"pageSize":5
}
}
//example 2
{
"expression": "firmwareName like 'firmware1'",
"pagination": {
"pageNo": 1,
"pageSize": 5
}
}
//example 3
{
"expression": "name like 'name' and firmwareName like 'firmware1'"
}
Return Sample¶
{
"code":0,
"msg":"OK",
"requestId":"99344e67-c79b-46bd-91d1-3ce3503ae769",
"data":[
{
"orgId":"yourOrgId",
"productKey":"yourProductKey",
"jobId":"yourJobId",
"name":{
"defaultValue":"name",
"i18nValue":{
"en_US":"name",
"zh_CN":"中文名",
"es_ES":"nombre",
"ja_JP":"名前"
}
},
"firmwareId":"5ed0dd4a646542001b3d113f",
"firmwareVersion":"1.1.0",
"firmwareName":{
"defaultValue":"firmware1",
"i18nValue":{
}
},
"type":"upgrade",
"enableUpgradeRequest":true,
"upgradePolicy":null,
"upgradeScope":{
"type":"total",
"versionNumbers":[
"1.0"
],
"deviceKeys":null,
"attributes":null,
"tags":null,
"assetTrees":null
},
"upgradeTimeout":7200,
"startSchedule":null, //deprecated
"endSchedule":null, //deprecated
"status":"started",
"createTime":1591171274788
}
],
"pagination":{
"sortedBy":null,
"pageNo":1,
"pageSize":5,
"totalSize":1
}
}