CreateOTAStaticUpgradeJob_物联网平台_API文档

插件下载了解更多
VS Code 插件
安装插件之前,确保已安装 VS Code安装插件之前,确保已安装 VS Code
Alibaba Cloud Developer Toolkit is a collection of extensions that can help access Alibaba Cloud services in Visual Studio Code.
JetBrains 插件
安装插件之前,确保已安装 JetBrains IDE安装插件之前,确保已安装 JetBrains IDE
The Alibaba Cloud Developer Toolkit for JetBrains makes it easier to access Alibaba Cloud services.

接口说明

使用说明

  • 若在调用 CreateOTAFirmware 接口创建升级包时,未指定“升级包可不通过验证”,则调用本接口创建批量升级批次前,必须保证升级包已验证成功。关于如何创建验证升级包任务,请参见 CreateOTAVerifyJob
  • 单次调用,对于定向升级,若直接传入设备名称,则最多可对 200 个设备发起升级任务;若使用待升级设备列表文件,则最多可对 10,000 个设备发起升级任务,需提前调用 GenerateDeviceNameListURL 生成文件 URL,并按说明上传设备列表文件。
  • 对多个设备发起升级任务时,如果某设备已经是目标版本,则过滤该设备,继续升级任务。
  • 同一设备只能同时在一个升级批次中处于待升级或正在升级状态。对处于待升级或正在升级状态的设备发起新的升级任务,后发起的任务会直接失败。
  • 可以对单个升级包,同时发起多个静态升级批次。
  • 当前日本(东京)和美国(弗吉尼亚)地域下,不支持创建静态分组升级批次,即 TargetSelection 不支持传入 GROUP
  • 当前仅中国的华东 2(上海)、华北 2(北京)和华南 1(深圳)地域下,支持使用 MQTT 协议下载升级包。

QPS 限制

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

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

流控信息

请求速率为10/1(s)。更多流控信息,请前往配额中心查看

授权信息

如下是此API对应的授权信息,用于RAM权限策略语句的Action元素中,为RAM用户或RAM角色授予调用此API的权限。请通过 RAM 访问控制设置,使用方法可参考访问控制帮助文档

具体说明如下:展开详情

操作访问级别资源类型条件关键字关联操作
iot:CreateOTAStaticUpgradeJob
Create
全部资源
*

请求参数

字段名称字段详情
IotInstanceIdstring

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

示例值:iot-cn-0pp1n8t****
FirmwareIdstring

升级包 ID,升级包的唯一标识符。展开详情

示例值:nx3xxVvFdwvn6dim50PY03****参考取值来源:
    ListOTAFirmware
    CreateOTAFirmware
ProductKeystring

升级包所属产品的 ProductKey

示例值:a1Le6d0****参考取值来源:
    CreateProduct
    QueryProductList
    ReleaseProduct
    ListProductByTags
    BindLicenseProduct
    BatchBindProductsIntoProject
TargetSelectionstring

升级范围。展开详情

示例值:ALL
ScheduleTimeinteger<int64>

指定发起 OTA 升级的时间。展开详情

注意 该字段类型为 Long,在序列化/反序列化的过程中可能导致精度丢失,请注意数值不得大于 9007199254740991。
示例值:1577808000000
RetryIntervalinteger<int32>

设备升级失败后,自动重试的时间间隔,单位为分钟。可选值:展开详情

示例值:60
RetryCountinteger<int32>

自动重试次数。展开详情

示例值:1
TimeoutInMinutesinteger<int32>

设备升级超时时间,超过指定时间后,设备未完成升级,则升级失败。单位为分钟,取值范围为 1~1,440。展开详情

示例值:1440
MaximumPerMinuteinteger<int32>

每分钟最多向多少个设备推送升级包下载 URL。取值范围:10~10,000。展开详情

示例值:1000
GrayPercentstring

设置灰度比例。取值为字符串格式的百分比,小数点后最多 3 位小数,系统计算结果向下取整。灰度升级的设备至少为 1 个。展开详情

示例值:33.33
ScheduleFinishTimeinteger<int64>

指定结束升级的时间。展开详情

注意 该字段类型为 Long,在序列化/反序列化的过程中可能导致精度丢失,请注意数值不得大于 9007199254740991。
示例值:1577909000000
OverwriteModeinteger<int32>

是否覆盖之前的升级任务。取值:展开详情

示例值:1
DnListFileUrlstring

定向升级设备列表文件的 URL。展开详情

示例值:https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin
NeedPushboolean

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

示例值:true
NeedConfirmboolean

如需自主控制设备 OTA 升级时,可配置此参数,通过手机 App 来控制,设备是否可进行 OTA 升级。手机 App 需您自行开发。展开详情

示例值:false
GroupIdstring

分组 ID。展开详情

示例值:CtjzCkNuOx***参考取值来源:
    CreateDeviceGroup
GroupTypestring

分组类型,仅可取值LINK_PLATFORM展开详情

示例值:LINK_PLATFORM参考取值来源:
    QueryDeviceGroupList
DownloadProtocolstring

升级包下载协议,可选:HTTPS(默认)或 MQTT。设备端收到物联网平台推送的升级包下载信息后,通过该协议下载升级包。展开详情

示例值:HTTPS
MultiModuleModeboolean

设备是否支持多模块同时升级。展开详情

示例值:false
SrcVersionarray<string>

待升级版本号列表。展开详情

示例值:V1.0.1子级条数 <= 20
TargetDeviceNamearray<string>

定向升级的设备名称列表。展开详情

示例值:deviceName1子级条数 <= 200
Tagarray<object>

标签列表。

子级条数 <= 20

请求说明

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

返回参数

字段名称字段详情
Codestring

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

示例值:MissingFirmwareId
ErrorMessagestring

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

示例值:FirmwareId is mandatory for this action.
RequestIdstring

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

示例值:29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1
Successboolean

是否调用成功。展开详情

示例值:true
Dataobject

调用成功时,返回的升级批次信息。更多信息,请参见 Data 下参数说明。

返回示例

变更历史

暂无变更历史