创建批量任务
功能介绍
应用服务器可调用此接口为创建批量处理任务，对多个设备进行批量操作。当前支持批量软固件升级、批量创建设备、批量修改设备、批量删除设备、批量冻结设备、批量解冻设备、批量创建命令、批量创建消息任务。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
URI
POST /v5/iot/{project_id}/batchtasks
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
project_id |
是 |
String |
参数说明：项目ID。获取方法请参见 获取项目ID。 |
请求参数
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
X-Auth-Token |
否 |
String |
参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 |
|
Instance-Id |
否 |
String |
参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考 查看实例详情。 |
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
app_id |
否 |
String |
参数说明：资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，建议携带该参数指定创建的批量任务归属到哪个资源空间下，否则创建的批量任务将会归属到默认资源空间下。 取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
|
task_name |
是 |
String |
参数说明：批量任务名称。 取值范围：长度不超过128，只允许中文、字母、数字、下划线（_）的组合。 |
|
task_type |
是 |
String |
参数说明：批量任务类型。 取值范围：
|
|
task_mode |
否 |
String |
参数说明：批量任务的模式，当前只支持网关模式，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，若升级的设备为某个网关的子设备，则平台下发获取版本信息通知和平台下发升级通知将携带task_id（软固件升级批量任务的任务ID）和sub_device_count（批量任务中网关设备包含的升级子设备数量）字段。 取值范围：GATEWAY: 网关模式。 |
|
task_ext_info |
否 |
Object |
参数说明：批量任务额外扩展信息，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，平台下发获取版本信息通知和平台下发升级通知将携带该字段。 取值范围：最长不超过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，支持该参数。
|
|
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次。 |
|
retry_interval |
否 |
Integer |
参数说明：批量任务子任务失败后，自动重试时间间隔，单位：分钟。 取值范围：最大1440(24小时)，不传入此参数表示不重试，如果传入retry_count参数则需要传入该参数。 |
响应参数
状态码： 201
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
task_id |
String |
批量任务ID，创建批量任务时由物联网平台分配获得。 |
|
task_name |
String |
批量任务名称。 |
|
task_type |
String |
批量任务类型，取值范围：firmwareUpgrade，softwareUpgrade，createDevices，deleteDevices，freezeDevices，unfreezeDevices，createCommands，createAsyncCommands，createMessages，updateDeviceShadows。
|
|
task_mode |
String |
参数说明：批量任务的模式，当前只支持网关模式，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，若升级的设备为某个网关的子设备，则平台下发获取版本信息通知和平台下发升级通知将携带task_id（软固件升级批量任务的任务ID）和sub_device_count（批量任务中网关设备包含的升级子设备数量）字段。 取值范围：GATEWAY: 网关模式。 |
|
task_ext_info |
Object |
参数说明：批量任务额外扩展信息，当task_type为firmwareUpgrade，softwareUpgrade支持该参数。软固件升级的场景下，平台下发获取版本信息通知和平台下发升级通知将携带该字段。 取值范围：最长不超过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。
|
|
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次。 |
|
retry_interval |
Integer |
参数说明：批量任务子任务失败后，自动重试时间间隔，单位：分钟。 取值范围：最大1440(24小时)，不传入此参数表示不重试，如果传入retry_count参数则需要传入该参数。 |
请求示例
-
创建批量软件升级任务，指定设备升级。
POST https://{endpoint}/v5/iot/{project_id}/batchtasks { "app_id" : "Ev8FVvCfOdQDzrFrxSOemiw_aMca", "task_name" : "BatchSoftwareUpgradeTask", "task_type" : "softwareUpgrade", "targets" : [ "e495cf17-ff79-4294-8f64-4d367919d665" ], "document" : { "package_id" : "32822e5744a45ede319d2c50" }, "task_policy" : { "schedule_time" : "20151212T121212Z", "retry_count" : 5, "retry_interval" : 60 } } -
创建批量软件升级任务，指定设备组中设备进行升级。
POST https://{endpoint}/v5/iot/{project_id}/batchtasks { "app_id" : "Ev8FVvCfOdQDzrFrxSOemiw_aMca", "task_name" : "BatchSoftwareUpgradeTask", "task_type" : "softwareUpgrade", "document" : { "package_id" : "32822e5744a45ede319d2c50" }, "targets_filter" : { "group_ids" : [ "e495cf17-ff79-4294-8f64-4d367919d665" ] }, "task_policy" : { "schedule_time" : "20151212T121212Z", "retry_count" : 5, "retry_interval" : 60 } } -
创建批量注册设备任务，从文件中读取参数。
POST https://{endpoint}/v5/iot/{project_id}/batchtasks { "app_id" : "Ev8FVvCfOdQDzrFrxSOemiw_aMca", "task_name" : "BatchCreateDevicesTask", "task_type" : "createDevices", "task_policy" : { "schedule_time" : "20151212T121212Z", "retry_count" : 5, "retry_interval" : 60 }, "document_source" : "jeQDJQZltU8iKgFFoW060F5SGZka" }
响应示例
状态码： 201
Created
{
"task_id" : "5c8ba99030344005c02316ad",
"task_name" : "testname",
"task_type" : "softwareUpgrade",
"targets" : [ "e495cf17-ff79-4294-8f64-4d367919d665" ],
"targets_filter" : {
"group_ids" : [ "e495cf17-ff79-4294-8f64-4d367919d665" ]
},
"document" : {
"package_id" : "32822e5744a45ede319d2c50"
},
"task_policy" : {
"schedule_time" : "20151212T121212Z",
"retry_count" : 5,
"retry_interval" : 60
},
"status" : "Success",
"status_desc" : "string",
"task_progress" : {
"total" : 0,
"processing" : 0,
"success" : 0,
"fail" : 0,
"waitting" : 0,
"fail_wait_retry" : 0,
"stopped" : 0
},
"create_time" : "20151212T121212Z"
}状态码
|
状态码 |
描述 |
|---|---|
|
201 |
Created |
|
400 |
BAD REQUEST |
|
401 |
Unauthorized |
|
403 |
FORBIDDEN |
|
500 |
Internal Server Error |
错误码
请参见错误码。
