创建任务

最近更新时间:2019-04-30 15:22:44

1. 接口描述

本接口(CreateTask)用于创建一个批量任务。目前此接口可以创建批量更新影子以及批量下发消息的任务。

接口请求域名:iotcloud.api.qcloud.com

注意:
一个帐号等待中以及处理中任务不能超过5个,否则接口会返回“等待和处理中的任务数过多”的模块错误码

2.输入参数

以下是请求参数列表仅列出了接口请求参数,其它参数见 公共请求参数 页面。

参数名称 必选 类型 描述
taskType String 取值为 “UpdateShadow” 或者 “PublishMessage”
productID String 执行任务的产品 ID
deviceNameFilter String 执行任务的设备名的正则表达式
tasks Json Object 任务描述细节,描述见下 Task
scheduleTimeInSeconds Int 任务开始执行的时间。 取值为 Unix 时间戳,单位秒,且需大于等于当前时间时间戳,0为系统当前时间时间戳,即立即执行,最大为当前时间86400秒后,超过则取值为当前时间86400秒后
maxExecutionTimeInSeconds Int 最长执行时间,单位秒,被调度后超过此时间仍未有结果则视为任务失败。取值为0-86400,默认为86400

Task 为一个 Json 对象,其内部定义为:

参数名称 必选 类型 描述
updateShadowTask Json Object 批量更新影子任务的描述细节,当 taskType 取值为 “UpdateShadow” 时,此字段必填。描述见下 BatchUpdateShadow
publishMessageTask Json Object 批量下发消息任务的描述细节,当 taskType 取值为 “PublishMessage” 时,此字段必填。描述见下 BatchPublishMessage

BatchUpdateShadow 为一个 Json 对象,其内部定义为:

参数名称 必选 类型 描述
desired String 设备影子的期望状态,格式为 Json 对象序列化之后的字符串

BatchPublishMessage 为一个 Json 对象,其内部定义为:

参数名称 必选 类型 描述
topic String 消息发往的主题。为 Topic 权限中去除 ProductID 和 DeviceName 的部分,如 “event”
payload String 消息内容

3.输出参数

参数名称 类型 描述
code Int 公共错误码。0 表示成功,其他值表示失败,详见 公共错误码 页面。
message String 模块错误信息描述,格式为 "(模块错误码)模块错误信息" 详见本页面的 模块错误码
codeDesc String 模块错误码的英文描述
taskId String 创建的任务 ID

4.示例

批量更新影子

输入

  POST /v2/index.php HTTP/1.1
  Host: iotcloud.api.qcloud.com

  Action=CreateTask&taskType=UpdateShadow&deviceNameFilter=door$&scheduleTimeInSeconds=0&productID=ABCDE12345&tasks={"updateShadowTask":{"desired":"{\"state\":\"open\"}"}}&<公共请求参数>

输出

{
    "taskId": "5ad5aa513332ea4cb86e9ad5",
    "message": "",
    "codeDesc": "Success",
    "code": 0
}

批量推送消息

输入

  POST /v2/index.php HTTP/1.1
  Host: iotcloud.api.qcloud.com

  Action=CreateTask&taskType=PublishMessage&deviceNameFilter=^door&scheduleTimeInSeconds=0&productID=ABCDE12345&tasks={"publishMessageTask":{"payload":"close", "topic":"event"}}&<公共请求参数>

输出

{
    "taskId": "5ad5afbb3332ea4cb86e9ad8",
    "message": "",
    "codeDesc": "Success",
    "code": 0
}

模块错误码

模块错误码 描述
10002 参数非法
10004 产品不存在
10005 等待和处理中的任务数过多
10100 内部服务器错误,请联系技术人员
10101 请求参数非法