edit

预约任务

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

添加预约

您可以通过调用 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,如果不传,则删除所有