调用该接口查询指定OTA升级包的详细信息,包括升级包的名称、类型、状态等。

限制说明

  • 如果在企业版实例中调用该接口,请求参数IotInstanceId必须填写。否则,调用接口会失败。
  • 单个阿里云账号调用该接口的每秒请求数(QPS)最大限制为20。
说明 RAM用户共享阿里云账号配额。

调试

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

请求参数

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

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

FirmwareId String s8SSHiKjpBfrM3BSN0z803****

升级包ID,升级包的唯一标识符。

升级包ID是调用CreateOTAFirmware创建升级包时,返回的参数之一。

可以调用ListOTAFirmware,从返回参数中查看。

IotInstanceId String iot_instc_pu****_c*-v64********

实例ID。

  • 企业版实例:必须传入此参数。您可在物联网平台控制台的实例概览页面,查看您的企业版实例ID。
  • 公共实例:无需传入此参数。

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

返回数据

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

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

ErrorMessage String 系统异常

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

FirmwareInfo Struct

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

DestVersion String 4.0.0

当前升级包版本号。

FirmwareDesc String modified-WiFi-module

升级包描述信息。

FirmwareId String UfuxnwygsuSkVE0VCN****0100

升级包ID,升级包的唯一标识符。

FirmwareName String t3q5rkNm

升级包名称。

FirmwareSign String 3d04ab6462633508606e5f3daac8****

升级包内容的签名值。

FirmwareSize Integer 924

升级包文件大小,单位:MB。

FirmwareUrl String https://ota-***.aliyuncs.com/ota/572ef2fd12ca4791a5b21a9eb948****/5E962CF83DB1495E8337E9C8A4D1****.bin?Expires=1577587360&OSSAccessKeyId=cS8uRRy54Rsz****&Signature=farzC8%2FVMN4HYdEtXvdiC2OevH****

OSS存储升级包的URL。

ModuleName String WifiConfigModify

升级包的模块名称。

升级包模块用于区分同产品下设备的不同模块的升级。更多信息,请参见添加升级包中的自定义OTA模块

ProductKey String a19mzPZ****

升级包所属产品的ProductKey

ProductName String MyProduct

升级包所属产品的名称。

SignMethod String MD5

升级包签名方式。

SrcVersion String 1.0.0

待升级的升级包版本号。

说明 仅差分升级的升级包返回该参数。升级包类型的说明,请参见参数 Type的描述。
Status Integer 2

升级包状态。

  • 0:未验证。
  • 1:已验证。
  • 2:验证中。
  • 3:验证失败。
Type Integer 0

升级包类型。

  • 0:整包升级包,您上传的升级包文件包含完整的升级包,将推送整包升级包给设备进行升级。
  • 1:差分升级包,您上传的升级包文件仅包含新版本升级包与之前版本的差异部分,仅推送差异部分给设备进行升级。
Udi String {"ota_notice":"升级底层摄像头驱动,解决视频图像模糊的问题。"}

推送给设备的自定义信息。不限制文本内容的格式,长度不超过4096个字符。

创建升级任务后,物联网平台向设备推送升级通知时,会将该自定义信息下发给设备。

UtcCreate String 2019-12-28T02:42:22.000Z

创建升级包的时间,UTC格式。

UtcModified String 2019-12-28T02:42:41.000Z

升级包最后一次修改时的时间,UTC格式。

VerifyProgress Integer 0

升级包的验证进度。

  • 0:未验证。
  • 100:已完成验证。
  • 0至100之间的数值N:表示N%的设备已完成升级。升级包验证状态请根据返回参数Status判断。
RequestId String A01829CE-75A1-4920-B775-921146A1AB79

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

Success Boolean true

是否调用成功。

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

示例

请求示例

https://iot.cn-shanghai.aliyuncs.com/?Action=QueryOTAFirmware
&FirmwareId=s8SSHiKjpBfrM3BSN0z803****
&<公共请求参数>

正常返回示例

XML格式

<QueryOTAFirmwareResponse>
  <RequestId>A01829CE-75A1-4920-B775-921146A1AB79</RequestId>
  <FirmwareInfo>
        <SrcVersion></SrcVersion>
        <FirmwareSign>3d04ab6462633508606e5f3daac8****</FirmwareSign>
        <ProductKey>a19mzPZ****</ProductKey>
        <Type>0</Type>
        <UtcModified>2019-12-28T02:42:41.000Z</UtcModified>
        <SignMethod>MD5</SignMethod>
        <UtcCreate>2019-12-28T02:42:22.000Z</UtcCreate>
        <FirmwareSize>924</FirmwareSize>
        <Status>2</Status>
        <FirmwareId>UfuxnwygsuSkVE0VCN****0100</FirmwareId>
        <FirmwareDesc>modified-WiFi-module</FirmwareDesc>
        <FirmwareUrl>https://ota-***.aliyuncs.com/ota/572ef2fd12ca4791a5b21a9eb948****/5E962CF83DB1495E8337E9C8A4D1****.bin?Expires=1577587360&amp;OSSAccessKeyId=cS8uRRy54Rsz****&amp;Signature=farzC8%2FVMN4HYdEtXvdiC2OevH****</FirmwareUrl>
        <DestVersion>4.0.0</DestVersion>
        <ProductName>MyProduct</ProductName>
        <FirmwareName>t3q5rkNm</FirmwareName>
        <ModuleName>WifiConfigModify</ModuleName>
        <Udi>{"ota_notice":"升级底层摄像头驱动,解决视频图像模糊的问题。"}</Udi>
        <VerifyProgress>0</VerifyProgress>
  </FirmwareInfo>
  <Success>true</Success>
</QueryOTAFirmwareResponse>

JSON格式

{
  "RequestId": "A01829CE-75A1-4920-B775-921146A1AB79",
  "FirmwareInfo": {
    "SrcVersion": "",
    "FirmwareSign": "3d04ab6462633508606e5f3daac8****",
    "ProductKey": "a19mzPZ****",
    "Type": 0,
    "UtcModified": "2019-12-28T02:42:41.000Z",
    "SignMethod": "MD5",
    "UtcCreate": "2019-12-28T02:42:22.000Z",
    "FirmwareSize": 924,
    "Status": 2,
    "FirmwareId": "UfuxnwygsuSkVE0VCN****0100",
    "FirmwareDesc": "modified-WiFi-module",
    "FirmwareUrl": "https://ota-***.aliyuncs.com/ota/572ef2fd12ca4791a5b21a9eb948****/5E962CF83DB1495E8337E9C8A4D1****.bin?Expires=1577587360&OSSAccessKeyId=cS8uRRy54Rsz****&Signature=farzC8%2FVMN4HYdEtXvdiC2OevH****",
    "DestVersion": "4.0.0",
    "ProductName": "MyProduct",
    "FirmwareName": "t3q5rkNm",
    "ModuleName": "WifiConfigModify",
    "Udi":"{\"ota_notice\":\"升级底层摄像头驱动,解决视频图像模糊的问题。\"}",
    "VerifyProgress": 0
  },
  "Success": true
}