Queries the details of an update batch.

Usage notes

After you call the CreateOTAVerifyJob, CreateOTAStaticUpgradeJob, or CreateOTADynamicUpgradeJob API operation to create an update batch, the JobId parameter is returned. You can use this parameter to query the details of the update batch.

Limits

Each Alibaba Cloud account can run a maximum of 10 queries per second (QPS).

Note RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes QueryOTAJob

The operation that you want to perform. Set the value to QueryOTAJob.

JobId String Yes wahVIzGkCMuAUE2gDERM02****

The ID of the update batch.

After you call the CreateOTAVerifyJob, CreateOTAStaticUpgradeJob, or CreateOTADynamicUpgradeJob API operation to create the update batch, you can obtain the JobId parameter. You can also view the batch ID on the Update Package Details page of the IoT Platform console.

IotInstanceId String No iot-cn-0pp1n8t****

The ID of the instance. You can view the instance ID on the Overview page in the IoT Platform console.

Notice
  • If your instance has an ID, you must configure this parameter. If you do not set this parameter, the call fails.
  • If your instance has no Overview page or ID, you do not need to set this parameter.

For more information, see Overview.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information, see Common request parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code returned if the call fails. For more information, see Error codes.

Data Struct

The update batch information returned if the call is successful. For more information, see the following parameters.

DestVersion String 1.0.1

The destination firmware version of the update.

DownloadProtocol String HTTPS

The download protocol of the update package.

DynamicMode Integer 1

The mode of dynamic update. Valid values:

  • 1: constantly updates the devices that meet the conditions.
  • 2: updates only the devices that subsequently submit the latest firmware versions.

This parameter is returned only if you perform a dynamic update.

FirmwareId String UfuxnwygsuSkVE0VCN****0100

The ID of the update package.

GrayPercent String 50.00

The phase ratio of the phased update.

This parameter is returned only if you perform a phased update.

GroupId String CtjzCkNuOxUR***

The ID of the device group to be updated.

GroupName String test

The name of the device group to be updated.

JobDesc String batch upgrade

The description of the update batch.

JobId String HvKuBpuk3rdk6E92CP****0200

The ID of the update batch.

JobStatus String IN_PROGRESS

The status of the update batch.

  • PLANNED: The update batch is being planned. The batch is created, but the scheduled time has not arrived. This parameter is returned only if you perform a static update.
  • IN_PROGRESS: The update batch is running.
  • COMPLETED: The update batch is completed.
  • CANCELED: The update batch is canceled.
JobType String UPGRADE_FIRMWARE

The type of the batch. Valid values:

  • VERFIY_FIRMWARE: update package verification.
  • UPGRADE_FIRMWARE: batch update.
MaximumPerMinute Integer 1000

The maximum number of devices to which the download URL of the update package is pushed per minute.

MultiModuleMode Boolean false

Specifies whether the device supports simultaneous updates of multiple modules.

  • false (default): no.
  • true: yes.

For more information, see Overview.

Name String Firmware2

The name of the update package.

NeedConfirm Boolean false

Specifies whether to confirm the update by using your mobile app.

NeedPush Boolean true

Specifies whether to automatically push update tasks from IoT Platform to devices.

OverwriteMode Integer 1

Specifies whether to overwrite the previous update task. Valid values:

  • 1: The previous update task is not overwritten. If a device already has an update task, the previous update task is implemented.
  • 2: The previous update task is overwritten. Only the current update task is implemented.

The update task that is in progress is not overwritten.

ProductKey String a19mzPZ****

The ProductKey of the product to which the update package belongs.

RetryCount Integer 1

The number of automatic retries after a device fails to be updated.

This parameter is returned if a retry policy is set when you create the update batch.

RetryInterval Integer 60

The automatic retry interval after a device fails to be updated. Unit: minutes.

This parameter is returned if a retry policy is set when you create the update batch.

SelectionType String STATIC

The update policy of the update batch. Valid values:

  • DYNAMIC: dynamic update. This value is returned if you call the CreateOTADynamicUpgradeJob API operation to create an update batch.
  • STATIC: static update. This value is returned if you call the CreateOTAStaticUpgradeJob API operation to create an update batch.
SrcVersions List null

The list of firmware versions to be updated.

Tags Array of OtaTagDTO

The tags of the update batch.

OtaTagDTO
Key String key1

The key of each tag.

Value String value1

The value of the tag.

TargetSelection String SPECIFIC

The scope of the update batch. Valid values:

  • ALL: updates all devices.
  • SPECIFIC: updates specified devices.
  • GRAY: performs a phased update.
Note The value ALL is returned if you call the CreateOTADynamicUpgradeJob API operation to create an update batch.
TimeoutInMinutes Integer 5

The timeout period of the device update. Unit: minutes.

This parameter is returned if the timeout period is set when you create the update batch.

UtcCreate String 2019-12-28T02:43:10.000Z

The time when the update batch was created. The time is displayed in UTC.

UtcEndTime String 2019-12-29T02:43:10.000Z

The end time of the update batch. The time is displayed in UTC.

This parameter is returned only after the update batch is completed.

UtcModified String 2019-12-28T02:43:10.000Z

The time when the update batch was last modified. The time is displayed in UTC.

UtcScheduleFinishTime String 2019-12-30T02:43:10.000Z

The end time of the scheduled update batch. This parameter is returned only if the update batch is scheduled and the end time of the scheduled update batch is specified.

UtcScheduleTime String 2019-12-29T02:43:10.000Z

The start time of the scheduled update batch. This parameter is returned only for scheduled update batches.

UtcStartTime String 2019-12-28T02:43:10.000Z

The start time of the update batch. The time is displayed in UTC.

ErrorMessage String A system exception occurred.

The error message returned if the call fails.

RequestId String 30F1BB8D-EDBF-44FD-BBC0-BE97DEA73991

The ID of the request.

Success Boolean true

Indicates whether the call was successful.

  • true: The call was successful.
  • false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=QueryOTAJob
&JobId=wahVIzGkCMuAUE2gDERM02****
&<Common request parameters>

Sample success responses

XML format 

<QueryOTAJobResponse>
  <Data>
        <TimeoutInMinutes>5</TimeoutInMinutes>
        <JobDesc>batch upgrade</JobDesc>
        <DownloadProtocol>HTTPS</DownloadProtocol>
        <UtcStartTime>2019-12-28T02:43:10.000Z</UtcStartTime>
        <UtcEndTime>2019-12-29T02:43:10.000Z</UtcEndTime>
        <ProductKey>a19mzPZ****</ProductKey>
        <UtcModified>2019-12-28T02:43:10.000Z</UtcModified>
        <JobStatus>IN_PROGRESS</JobStatus>
        <UtcCreate>2019-12-28T02:43:10.000Z</UtcCreate>
        <SelectionType>STATIC</SelectionType>
        <TargetSelection>SPECIFIC</TargetSelection>
        <JobType>UPGRADE_FIRMWARE</JobType>
        <GroupId></GroupId>
        <GroupName></GroupName>
        <RetryInterval>60</RetryInterval>
        <RetryCount>1</RetryCount>
        <OverwriteMode>1</OverwriteMode>
        <MultiModuleMode>true</MultiModuleMode>
        <MaximumPerMinute>1000</MaximumPerMinute>
        <SrcVersions>
              <SrcVersion>1.0.0</SrcVersion>
        </SrcVersions>
        <Name>firmware2</Name>
        <NeedConfirm>true</NeedConfirm>
        <NeedPush>false</NeedPush>
        <FirmwareId>UfuxnwygsuSkVE0VCN****0100</FirmwareId>
        <JobId>HvKuBpuk3rdk6E92CP****0200</JobId>
        <DestVersion>1.0.1</DestVersion>
  </Data>
  <RequestId>30F1BB8D-EDBF-44FD-BBC0-BE97DEA73991</RequestId>
  <Success>true</Success>
</QueryOTAJobResponse>

JSON format 

{
  "Data": {
    "TimeoutInMinutes": 5,
    "JobDesc": "batch upgrade",
    "DownloadProtocol":"HTTPS",
    "UtcStartTime": "2019-12-28T02:43:10.000Z",
    "UtcEndTime": "2019-12-29T02:43:10.000Z",
    "ProductKey": "a19mzPZ****",
    "UtcModified": "2019-12-28T02:43:10.000Z",
    "JobStatus": "IN_PROGRESS",
    "UtcCreate": "2019-12-28T02:43:10.000Z",
    "SelectionType": "STATIC",
    "TargetSelection": "SPECIFIC",
    "JobType": "UPGRADE_FIRMWARE",
    "GroupId":"",
    "GroupName":"",
    "RetryInterval":60,
    "RetryCount":1,
    "OverwriteMode":1,
    "MultiModuleMode":true,
    "MaximumPerMinute":1000,
    "SrcVersions": {
      "SrcVersion": ["1.0.0"]
    },
    "Name":"firmware2",
    "NeedConfirm":true,
    "NeedPush":false,
    "FirmwareId": "UfuxnwygsuSkVE0VCN****0100",
    "JobId": "HvKuBpuk3rdk6E92CP****0200",
    "DestVersion": "1.0.1"
  },
  "RequestId": "30F1BB8D-EDBF-44FD-BBC0-BE97DEA73991",
  "Success": true
}

Error codes

For a list of error codes, visit the API Error Center.