创建批量任务

project_id

是

String

参数说明：项目ID。获取方法请参见 获取项目ID。

X-Auth-Token

否

String

参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。

Instance-Id

否

String

参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考 查看实例详情。

最小长度：1

最大长度：36

app_id

否

String

参数说明：资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，建议携带该参数指定创建的批量任务归属到哪个资源空间下，否则创建的批量任务将会归属到默认资源空间下。 取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。

task_name

是

String

参数说明：批量任务名称。 取值范围：长度不超过128，只允许中文、字母、数字、下划线（_）的组合。

最小长度：1

最大长度：128

task_type

是

String

参数说明：批量任务类型。 取值范围：

• softwareUpgrade: 软件升级任务

• firmwareUpgrade: 固件升级任务

• createDevices: 批量创建设备任务

• deleteDevices: 批量删除设备任务

• freezeDevices: 批量冻结设备任务

• unfreezeDevices: 批量解冻设备任务

• createCommands: 批量创建同步命令任务

• createAsyncCommands: 批量创建异步命令任务

• createMessages: 批量创建消息任务

• updateDeviceShadows：批量配置设备影子任务

• updateDevices：批量更新设备任务

task_mode

否

String

参数说明：批量任务的模式，当前只支持网关模式，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，若升级的设备为某个网关的子设备，则平台下发获取版本信息通知和平台下发升级通知将携带task_id（软固件升级批量任务的任务ID）和sub_device_count（批量任务中网关设备包含的升级子设备数量）字段。 取值范围：GATEWAY: 网关模式。

task_ext_info

否

Object

参数说明：批量任务额外扩展信息，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，平台下发获取版本信息通知和平台下发升级通知将携带该字段。 取值范围：最长不超过512个字符。

最大长度：512

targets

否

Array of strings

参数说明：执行批量任务的目标，此处填写device_id列表，且最多支持3万个device_id。当task_type为firmwareUpgrade，softwareUpgrade，deleteDevices，freezeDevices，unfreezeDevices，createCommands，createAsyncCommands，createMessages，updateDeviceShadows，支持该参数。同时使用targets、targets_filter、document_source参数时，只有一个参数会生效，且平台优先使用targets，其次是targets_filter，最后是document_source。 取值范围：device_id列表。device_id支持长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。

targets_filter

否

Map<String,Object>

参数说明：任务目标筛选参数。Json格式，里面是一个个键值对，（K,V）格式标识筛选targets需要的参数，目前支持的K有group_ids（V填写group_id数组，eg:["e495cf17-ff79-4294-8f64-4d367919d665"]，任务则会筛选出来符合该群组条件的设备作为目标）。当task_type为firmwareUpgrade，softwareUpgrade，deleteDevices，freezeDevices，unfreezeDevices，createCommands，createAsyncCommands，createMessages，updateDeviceShadows，支持该参数。同时使用targets、targets_filter、document_source参数时，只有一个参数会生效，且平台优先使用targets，其次是targets_filter，最后是document_source。

document

否

Object

参数说明：执行任务数据文档，Json格式，Json里面是(K,V)键值对。当task_type为firmwareUpgrade，softwareUpgrade，createCommands，createAsyncCommands，createMessages，updateDeviceShadows，支持该参数。

• softwareUpgrade|firmwareUpgrade，需要填写key为package_id，value为在平台上传的软固件附件id，id由portal软件库包管理上传并查询获得。eg：“{"package_id": "32822e5744a45ede319d2c50"}”。

• createCommands，需要填写同步命令相关参数，eg：“{"service_id":"water","command_name":"ON_OFF","paras":{"value":"ON"}}”，参考设备同步命令)。

• createAsyncCommands，需要填写异步命令相关参数，eg：“{"service_id":"water","command_name":"ON_OFF","paras":{"value":"ON"},"expire_time":0,"send_strategy":"immediately"}”，参考设备异步命令)。

• createMessages，需要填写消息下发相关参数，eg：“{"message_id":"99b32da9-cd17-4cdf-a286-f6e849cbc364","name":"messageName","message":"HelloWorld","encoding":"none","payload_format":"standard","topic":"messageDown","topic_full_name":"/device/message/down"}”，参考下发设备消息)。

• updateDeviceShadows，需要填写配置设备影子相关参数，eg：“{"shadow": [{"service_id": "WaterMeter","desired": {"temperature": "60"}}]}”，参考配置设备影子预期数据)。限制说明：1. service_id和desired参数必填。2. 配置的service_id数量不大于5个且service_id不能重复。3. 配置参数内容大小不超过10K。

task_policy

否

TaskPolicy object

参数说明：任务策略请求信息。

document_source

否

String

参数说明：上传的批量任务文件ID。当task_type为createDevices，updateDevices，deleteDevices，freezeDevices，unfreezeDevices时，支持该参数。使用该参数时，需要先调用批量任务的文件管理接口上传文件来获取文件ID，文件样例请参见 批量注册设备模板，批量更新设备模板，批量删除设备模板，批量冻结设备模板，批量解冻设备模板。同时使用targets、targets_filter、document_source参数时，只有一个参数会生效，且平台优先使用targets，其次是targets_filter，最后是document_source。

schedule_time

否

String

参数说明：批量任务指定执行时间。 取值范围：7天内，不传入此参数表示立即执行，格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

retry_count

否

Integer

参数说明：批量任务子任务自动重试次数。 取值范围：如果传入retry_interval参数，则需传入该参数，最大支持重试5次。

最小值：1

最大值：5

retry_interval

否

Integer

参数说明：批量任务子任务失败后，自动重试时间间隔，单位：分钟。 取值范围：最大1440(24小时)，不传入此参数表示不重试，如果传入retry_count参数则需要传入该参数。

最小值：0

最大值：1440

task_id

String

批量任务ID，创建批量任务时由物联网平台分配获得。

task_name

String

批量任务名称。

task_type

String

批量任务类型，取值范围：firmwareUpgrade，softwareUpgrade，createDevices，deleteDevices，freezeDevices，unfreezeDevices，createCommands，createAsyncCommands，createMessages，updateDeviceShadows。

• softwareUpgrade: 软件升级任务

• firmwareUpgrade: 固件升级任务

• createDevices: 批量创建设备任务

• deleteDevices: 批量删除设备任务

• freezeDevices: 批量冻结设备任务

• unfreezeDevices: 批量解冻设备任务

• createCommands: 批量创建同步命令任务

• createAsyncCommands: 批量创建异步命令任务

• createMessages: 批量创建消息任务

• updateDeviceShadows: 批量配置设备影子任务

• updateDevices：批量更新设备任务

task_mode

String

参数说明：批量任务的模式，当前只支持网关模式，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，若升级的设备为某个网关的子设备，则平台下发获取版本信息通知和平台下发升级通知将携带task_id（软固件升级批量任务的任务ID）和sub_device_count（批量任务中网关设备包含的升级子设备数量）字段。 取值范围：GATEWAY: 网关模式。

task_ext_info

Object

参数说明：批量任务额外扩展信息，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，平台下发获取版本信息通知和平台下发升级通知将携带该字段。 取值范围：最长不超过512个字符。

最大长度：512

targets

Array of strings

执行批量任务的目标，当task_type为firmwareUpgrade，softwareUpgrade，deleteDevices，freezeDevices，unfreezeDevices，createCommands，createAsyncCommands，createMessages，updateDeviceShadows，此处填写device_id列表。

targets_filter

Map<String,Object>

任务目标筛选参数。Json格式，里面是一个个键值对，（K,V）格式标识筛选targets需要的参数，目前支持的K有group_ids（V填写group_id数组，eg:["e495cf17-ff79-4294-8f64-4d367919d665"]，任务则会筛选出来符合该群组条件的设备作为目标）

document

Object

执行任务数据文档，Json格式。(当task_type为softwareUpgrade|firmwareUpgrade，也就是软固件升级任务时，Json里面是(K,V)键值对，需要填写key为package_id，value为在平台上传的软固件附件id，id由portal软件库包管理上传并查询获得。当task_type为createCommands，也就是批量创建同步命令任务时，Json里面是命令相关参数，eg：{"service_id":"water","command_name":"ON_OFF","paras":{"value":"ON"}}，参考设备同步命令)。当task_type为createAsyncCommands，也就是批量创建异步命令任务时，Json里面是命令相关参数，eg：{"service_id":"water","command_name":"ON_OFF","paras":{"value":"ON"},"expire_time":0,"send_strategy":"immediately"}，参考设备异步命令)。当task_type为updateDeviceShadows，也就是批量配置设备影子任务时，Json里面是命令相关参数，eg：{"shadow": [{"service_id": "WaterMeter","desired": {"temperature": "60"}}]}，参考配置设备影子预期数据)。

task_policy

TaskPolicy object

任务执行策略。

status

String

批量任务的状态，可选参数，取值范围：Success|Fail|Processing|PartialSuccess|Stopped|Waitting|Initializing|Stopping。

• Initializing: 初始化中。

• Waitting: 等待中。

• Processing: 执行中。

• Success: 成功。

• Fail: 失败。

• PartialSuccess: 部分成功。

• Stopped: 停止。

• Stopping 停止中。

status_desc

String

批量任务状态描述(包含主任务失败错误信息)

task_progress

TaskProgress object

子任务执行统计结果。

create_time

String

批量任务的创建时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

schedule_time

String

参数说明：批量任务指定执行时间。 取值范围：7天内，不传入此参数表示立即执行，格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

retry_count

Integer

参数说明：批量任务子任务自动重试次数。 取值范围：如果传入retry_interval参数，则需传入该参数，最大支持重试5次。

最小值：1

最大值：5

retry_interval

Integer

参数说明：批量任务子任务失败后，自动重试时间间隔，单位：分钟。 取值范围：最大1440(24小时)，不传入此参数表示不重试，如果传入retry_count参数则需要传入该参数。

最小值：0

最大值：1440

total

Integer

子任务总个数。

processing

Integer

正在执行的子任务个数。

success

Integer

执行成功的子任务个数。

fail

Integer

执行失败的的子任务个数。

waitting

Integer

等待执行的子任务个数。

fail_wait_retry

Integer

失败等待重试的子任务个数。

stopped

Integer

停止的子任务个数。

removed

Integer

移除的子任务个数。

201

Created

400

BAD REQUEST

401

Unauthorized

403

FORBIDDEN

500

Internal Server Error