预约任务¶

预约任务类似手机上的待办事项、闹钟。氦氪提供了基于软服务和硬件服务的预约服务，要实现预约功能，提交一个预约任务即可。

添加预约¶

您可以通过调用 4.4.5 添加预约任务 来创建一个预约任务，考虑该API 调用较为复杂，故该API除了最一般的调用方式外，还提供了几种简便调用方式，如下：

最一般创建，触发时间使用quartz cron表达式来表述。
一次性预约，所谓一次性，是指任务在未来一个时间点执行，且执行一次。
循环预约任务，所谓循环，是指一周中某几天的某个时间点执行，如不删除则一直执行。

以下是不同的调用方式：

1.通用方式(quartz cron)¶

创建每周一、周二、周四12：00定时下发命令（cmdId=1）：

PUT /rule/schedulerTask?devTid=&ctrlKey= HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
    "taskId": 0,
    "taskName": "我的预约",
    "desc": "周一、周二、周四 12:00 触发",
    "code": {
        "raw": "1237612371",
        "cmdId": 1
    },
    "schedulerType": "GENERIC",
    "timeZoneOffset": 480,
    "enable": true,
    "cronExpr": "0 0 12 ? * MON,TUE,THU *",
    "subDevTid": ""
}

请求参数¶

参数	是否必须	含义
devTid	true	设备ID
ctrlKey	true	设备控制码

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "uid": "46602594440",
    "taskId": 0,
    "taskName": "我的预约",
    "taskKey": null,
    "enable": true,
    "code": {
      "raw": "1237612371",
      "cmdId": 1
    },
    "desc": "周一、周二、周四 12:00 触发",
    "timeZoneOffset": 480,
    "count": 0,
    "timerTaskStatus": "FREEZE",
    "createTime": 1484898296709,
    "updateTime": 1484898296709,
    "subDevTid": "",
    "schedulerType": "GENERIC",
    "cronExpr": "0 0 12 ? * MON,TUE,THU *",
    "triggerDateTime": null,
    "triggerTime": null,
    "repeatList": null,
    "expired": false,
    "nextTriggerTime": 1485144000000,
    "serverTime": {
      "hour": 15,
      "minute": 44,
      "second": 56,
      "nano": 740000000,
      "year": 2017,
      "month": "JANUARY",
      "dayOfYear": 20,
      "dayOfWeek": "FRIDAY",
      "dayOfMonth": 20,
      "monthValue": 1,
      "chronology": {
        "id": "ISO",
        "calendarType": "iso8601"
      }
    },
    "serverTimeZoneOffset": 480
  }
]

Response¶

参数	是否必须	说明
taskId	false	预约任务id，如果为空表示创建，非空表示更新。创建时，如果预约超过最大数量（与产品偏好设置有关，比如10）将会替换最早的预约任务
taskName	true	命令名称
desc	true	命令描述
code	true	下发的命令
schedulerType	true	预约类型[GENERIC, ONCE, LOOP]
timeZoneOffset	true	时区偏移（分钟），比如北京时间（东八区)为480
enable	true	是否启用
cronExpr	true	cron表达式一共7位，最后一位是年份
subDevTid	false	子设备ID

2.一次性预约¶

PUT /rule/schedulerTask?devTid=&ctrlKey= HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
  "taskId": 0,
  "taskName": "我的预约",
  "desc" : "2016.1.7 12:00 触发",
  "code" : { 
    "raw" : "1237612371", 
    "cmdId" : 1
  },
  "schedulerType": "ONCE",
  "timeZoneOffset" : 480,    
  "enable": true,
  "triggerDateTime" : "2016-01-07T12:00:00",
  "subDevTid": ""
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "uid": "46602594440",
    "taskId": 0,
    "taskName": "我的预约",
    "taskKey": null,
    "enable": true,
    "code": {
      "raw": "1237612371",
      "cmdId": 1
    },
    "desc": "2016.1.7 12:00 触发",
    "timeZoneOffset": 480,
    "count": 0,
    "timerTaskStatus": "FREEZE",
    "createTime": 1484898392825,
    "updateTime": 1484898392825,
    "subDevTid": "",
    "schedulerType": "ONCE",
    "cronExpr": "0 0 12 7 1 ? 2016",
    "triggerDateTime": "2016-01-07T12:00",
    "triggerTime": null,
    "repeatList": null,
    "expired": true,
    "nextTriggerTime": null,
    "serverTime": {
      "hour": 15,
      "minute": 46,
      "second": 32,
      "nano": 872000000,
      "year": 2017,
      "month": "JANUARY",
      "dayOfYear": 20,
      "dayOfWeek": "FRIDAY",
      "dayOfMonth": 20,
      "monthValue": 1,
      "chronology": {
        "id": "ISO",
        "calendarType": "iso8601"
      }
    },
    "serverTimeZoneOffset": 480
  }
]

请求参数¶

参数	是否必须	说明
devTid	true	设备ID
ctrlKey	true	设备控制码

请求体¶

参数	是否必须	说明
triggerDateTime	true	触发时间，ISO8601 格式时间
schedulerType	true	预约类型[GENERIC, ONCE, LOOP]

3.循环预约任务¶

PUT /rule/schedulerTask?devTid=&ctrlKey= HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
  "taskId": 0,
  "taskName": "我的预约",
  "desc" : "周一、周二、周四 12:00 触发",
  "code" : { 
    "raw" : "1237612371", 
    "cmdId" : 1
  },
  "schedulerType": "LOOP",
  "timeZoneOffset" : 480,    
  "enable": true,
  "triggerTime" : "12:00:00",
  "repeatList" : ["MON", "TUE", "THU"],
  "subDevTid": ""
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "uid": "46602594440",
    "taskId": 0,
    "taskName": "我的预约",
    "taskKey": null,
    "enable": true,
    "code": {
      "raw": "1237612371",
      "cmdId": 1
    },
    "desc": "周一、周二、周四 12:00 触发",
    "timeZoneOffset": 480,
    "count": 0,
    "timerTaskStatus": "FREEZE",
    "createTime": 1484898613469,
    "updateTime": 1484898613469,
    "subDevTid": "",
    "schedulerType": "LOOP",
    "cronExpr": "0 0 12 ? * MON,TUE,THU *",
    "triggerDateTime": null,
    "triggerTime": "12:00",
    "repeatList": [
      "MON",
      "TUE",
      "THU"
    ],
    "expired": false,
    "nextTriggerTime": 1485057600000,
    "serverTime": {
      "hour": 15,
      "minute": 50,
      "second": 13,
      "nano": 536000000,
      "year": 2017,
      "month": "JANUARY",
      "dayOfYear": 20,
      "dayOfWeek": "FRIDAY",
      "dayOfMonth": 20,
      "monthValue": 1,
      "chronology": {
        "id": "ISO",
        "calendarType": "iso8601"
      }
    },
    "serverTimeZoneOffset": 480
  }
]

请求参数¶

参数	是否必须	说明
devTid	true	设备ID
ctrlKey	true	设备控制码

请求体¶

参数	是否必须	说明
schedulerType	true	预约类型[GENERIC, ONCE, LOOP]
triggerTime	true	本地时间（不包含日期）
repeatList	true	重复的的星期日[MON, TUE, WED, THU, FRI, SAT, FRI]

这里 code 参数为当任务触发时执行的指令，详细请参考 产品控制台--产品管理 或咨询您的设备产品设计负责人。当您通过 Hekr 定时预约管理 REST API 创建了一个定时预约任务后，Hekr Cloud 会向指定的设备发送 devSync指令，设备随即会发起 getTimerList 请求来同步拉取未来30min时间段内将会被触发的预约任务并缓存在设备的内存中。同时注意设备亦会定时拉取预约任务列表进行同步。

以上流程如下图所示:

列举预约¶

您可以通过调用 4.4.6 列举预约任务 列举当前设备上所有的预约任务：

GET /rule/schedulerTask?devTid=&ctrlKey=&taskId= HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "uid": "46602594440",
    "taskId": 0,
    "taskName": "我的预约",
    "taskKey": null,
    "enable": true,
    "code": {
      "raw": "1237612371",
      "cmdId": 1
    },
    "desc": "周一、周二、周四 12:00 触发",
    "timeZoneOffset": 480,
    "count": 0,
    "timerTaskStatus": "FREEZE",
    "createTime": 1484898995329,
    "updateTime": 1484898995329,
    "subDevTid": "",
    "schedulerType": "LOOP",
    "cronExpr": "0 0 12 ? * MON,TUE,THU *",
    "triggerDateTime": null,
    "triggerTime": "12:00",
    "repeatList": [
      "MON",
      "TUE",
      "THU"
    ],
    "expired": false,
    "nextTriggerTime": 1485057600000,
    "serverTime": {
      "hour": 15,
      "minute": 56,
      "second": 53,
      "nano": 13000000,
      "year": 2017,
      "month": "JANUARY",
      "dayOfYear": 20,
      "dayOfWeek": "FRIDAY",
      "dayOfMonth": 20,
      "monthValue": 1,
      "chronology": {
        "id": "ISO",
        "calendarType": "iso8601"
      }
    },
    "serverTimeZoneOffset": 480
  }
]

请求参数¶

参数	是否必须	说明
devTid	true	设备ID
ctrlKey	true	设备控制码
taskId	false	预约任务过滤ID（列表），不传则返回所有，可以使用以`,`分割列表，如`0,1,2`

删除预约¶

DELETE /rule/schedulerTask?devTid=&ctrlKey=&taskId= HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[]

请求参数¶

参数	是否必须	说明
devTid	true	设备ID
ctrlKey	true	设备控制码
taskId	false	想要删除预约的ID，如果不传，则删除所有