调用该接口查询指定升级批次的详情。

使用说明

您可调用CreateOTAVerifyJobCreateOTAStaticUpgradeJobCreateOTADynamicUpgradeJob创建升级任务批次后,根据返回的JobId查看升级批次的详情。

QPS限制

单个阿里云账号调用该接口的每秒请求数(QPS)最大限制为10。

说明 RAM用户共享阿里云账号配额。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String QueryOTAJob

系统规定参数。取值:QueryOTAJob。

JobId String wahVIzGkCMuAUE2gDERM02****

升级批次ID。

您调用CreateOTAVerifyJobCreateOTAStaticUpgradeJobCreateOTADynamicUpgradeJob创建升级任务批次后,返回的JobId。您也可以在物联网平台控制台的升级包详情页面查看。

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

实例ID。您可在物联网平台控制台的实例概览页面,查看当前实例的ID

注意
  • 若有ID值,必须传入该ID值,否则调用会失败。
  • 若无实例概览页面或ID值,则无需传入。

实例的更多信息,请参见实例概述

调用API时,除了本文介绍的该API的特有请求参数,还需传入公共请求参数。公共请求参数说明,请参见公共参数文档

返回数据

名称 类型 示例值 描述
Code String iot.system.SystemException

调用失败时,返回的错误码。更多信息,请参见错误码

Data Struct

调用成功时,返回的升级批次信息。详情见以下Data所包含的参数。

DestVersion String 1.0.1

升级目标版本号。

DownloadProtocol String HTTPS

升级包文件的下载协议。

DynamicMode Integer 1

动态升级模式。取值范围:

  • 1:除了升级当前满足升级条件的设备,还将持续检查设备是否满足升级条件,对满足升级条件的设备进行升级。
  • 2:仅对后续上报新版本号的设备生效。

仅升级策略为动态升级时,返回该参数。

FirmwareId String UfuxnwygsuSkVE0VCN****0100

升级包ID。

GrayPercent String 50.00

灰度升级的比例。

仅升级范围为灰度升级时,返回该参数。

GroupId String CtjzCkNuOxUR***

分组升级的设备分组ID。

GroupName String test

分组升级的设备分组名称。

JobDesc String batch upgrade

升级批次描述。

JobId String HvKuBpuk3rdk6E92CP****0200

升级批次ID,批次的唯一标识符。

JobStatus String IN_PROGRESS

批次的状态。

  • PLANNED:计划中。批次已创建,但是定时时间未到。仅定时静态升级的批次可能返回该值。
  • IN_PROGRESS:执行中。
  • COMPLETED:已完成。
  • CANCELED:已取消。
JobType String UPGRADE_FIRMWARE

批次类型。

  • VERIFY_FIRMWARE:升级包验证批次。
  • UPGRADE_FIRMWARE:批量升级批次。
MaximumPerMinute Integer 1000

每分钟最多向多少个设备推送升级包下载URL。

MultiModuleMode Boolean false

设备是否支持多模块同时升级。

  • false(默认):否,设备不支持多模块同时升级。
  • true:是,设备支持多模块同时升级。

更多信息,请参见设备支持多模块同时升级说明表

Name String Firmware2

升级包名称。

NeedConfirm Boolean false

是否App确认升级。

NeedPush Boolean true

物联网平台是否主动向设备推送升级任务。

OverwriteMode Integer 1

是否覆盖之前的升级任务。取值:

  • 1:不覆盖。若设备已有升级任务,则只执行已有任务。
  • 2:覆盖。设备只执行新的升级任务。

不覆盖升级中的任务。

ProductKey String a19mzPZ****

升级包所属产品的ProductKey。

RetryCount Integer 1

设备升级失败后,自动重试次数。

创建升级批次时,设置了失败重试策略,则返回该参数。

RetryInterval Integer 60

设备升级失败后,自动重试时间间隔,单位:分钟。

创建升级批次时,设置了失败重试策略,则返回该参数。

SelectionType String STATIC

升级策略。

SrcVersions List {"SrcVersion": ["1.0.0"]}

待升级版本号列表。

Tags Array of OtaTagDTO

升级批次标签。

OtaTagDTO
Key String key1

标签名。

Value String value1

标签值。

TargetSelection String SPECIFIC

升级范围。

  • ALL:全量升级。
  • SPECIFIC:定向升级。
  • GRAY:灰度升级。
说明 调用CreateOTADynamicUpgradeJob创建的动态升级批次,该参数仅返回ALL。
TimeoutInMinutes Integer 5

设备升级超时时间,单位:分钟。

创建升级批次时,设置了超时时间,则返回该参数。

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

批次创建时的时间,UTC格式。

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

该批次任务执行结束时的时间,UTC格式。

仅已执行结束的升级批次才返回此参数。

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

批次最后一次修改时的时间,UTC格式。

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

定时升级结束的时间。仅定时升级任务且设置了定时升级结束时间时会返回该参数。

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

定时升级发起的时间。仅定时升级任务会返回该参数。

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

该批次任务开始执行时的时间,UTC格式。

ErrorMessage String 系统异常

调用失败时,返回的出错信息。

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

阿里云为该请求生成的唯一标识符。

Success Boolean true

是否调用成功。

  • true:调用成功。
  • false:调用失败。

示例

请求示例

https://iot.cn-shanghai.aliyuncs.com/?Action=QueryOTAJob
&JobId=wahVIzGkCMuAUE2gDERM02****
&<公共请求参数>

正常返回示例

XML格式

<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格式

{
  "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
}

错误码

访问错误中心查看更多错误码。