查询批量任务
功能介绍
应用服务器可调用此接口查询物联网平台中指定批量任务的信息，包括任务内容、任务状态、任务完成情况统计以及子任务列表等。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
URI
GET /v5/iot/{project_id}/batchtasks/{task_id}
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
task_id |
是 |
String |
参数说明：批量任务ID，创建批量任务时由物联网平台分配获得。 取值范围：长度不超过24，只允许小写字母a到f、数字的组合。 |
|
project_id |
是 |
String |
参数说明：项目ID。获取方法请参见 获取项目ID。 |
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
task_detail_status |
否 |
String |
参数说明：子任务的执行状态，可选参数。 取值范围：
|
|
target |
否 |
String |
参数说明：执行批量任务的目标，当task_type为firmwareUpgrade，softwareUpgrade，deleteDevices，freezeDevices，unfreezeDevices，createCommands，createAsyncCommands，createMessages，updateDeviceShadows，此处填写device_id 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
|
limit |
否 |
Integer |
参数说明：分页查询时每页显示的记录数。 取值范围：1-50的整数，默认值为10。 |
|
marker |
否 |
String |
参数说明：上一次分页查询结果中最后一条记录的ID，在上一次分页查询时由物联网平台返回获得。分页查询时物联网平台是按marker也就是记录ID降序查询的，越新的数据记录ID也会越大。若填写marker，则本次只查询记录ID小于marker的数据记录。若不填写，则从记录ID最大也就是最新的一条数据开始查询。如果需要依次查询所有数据，则每次查询时必须填写上一次查询响应中的marker值。 取值范围：长度为24的十六进制字符串，默认值为ffffffffffffffffffffffff。 |
|
offset |
否 |
Integer |
参数说明：表示从marker后偏移offset条记录开始查询。默认为0，取值范围为0-500的整数。当offset为0时，表示从marker后第一条记录开始输出。限制offset最大值是出于API性能考虑，您可以搭配marker使用该参数实现翻页，例如每页50条记录，1-11页内都可以直接使用offset跳转到指定页，但到11页后，由于offset限制为500，您需要使用第11页返回的marker作为下次查询的marker，以实现翻页到12-22页。 取值范围：0-500的整数，默认为0。 |
请求参数
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
X-Auth-Token |
否 |
String |
参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 |
|
Instance-Id |
否 |
String |
参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考 查看实例详情。 |
响应参数
状态码： 200
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
batchtask |
Task object |
批量任务基本信息。 |
|
task_details |
Array of TaskDetail objects |
子任务详情列表。 |
|
page |
Page object |
查询结果的分页信息。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
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参数则需要传入该参数。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
total |
Integer |
子任务总个数。 |
|
processing |
Integer |
正在执行的子任务个数。 |
|
success |
Integer |
执行成功的子任务个数。 |
|
fail |
Integer |
执行失败的的子任务个数。 |
|
waitting |
Integer |
等待执行的子任务个数。 |
|
fail_wait_retry |
Integer |
失败等待重试的子任务个数。 |
|
stopped |
Integer |
停止的子任务个数。 |
|
removed |
Integer |
移除的子任务个数。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
target |
String |
执行批量任务的目标。 |
|
status |
String |
子任务的执行状态，结果范围：Processing，Success，Fail，Waitting，FailWaitRetry，Stopped。
|
|
output |
String |
子任务执行的输出信息。 |
|
error |
ErrorInfo object |
子任务执行失败信息。 |
请求示例
查询指定批量任务详情。
GET https://{endpoint}/v5/iot/{project_id}/batchtasks/{taskId}响应示例
状态码： 200
OK
{
"batchtask" : {
"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"
},
"task_details" : [ {
"target" : "e495cf17-ff79-4294-8f64-4d367919d665",
"status" : "Success",
"output" : "success",
"error" : {
"error_code" : "IOTDA.000002",
"error_msg" : "The request is unauthorized."
}
} ],
"page" : {
"count" : 10,
"marker" : "5c90fa7d3c4e4405e8525079"
}
}状态码
|
状态码 |
描述 |
|---|---|
|
200 |
OK |
|
400 |
Bad Request |
|
401 |
Unauthorized |
|
403 |
Forbidden |
|
404 |
Not Found |
|
500 |
Internal Server Error |
错误码
请参见错误码。
