云端定时

云端定时模块，提供定时任务查询、创建、修改、详情查询和批量删除等 API。

安装

npm install @quec-wx-mp/api-scheduled-task

import scheduledTask from '@quec-wx-mp/api-scheduled-task'
const plugin = requirePlugin('quecPlugin')

plugin.use(scheduledTask)

API 列表

| 方法 | 说明 | | ------------------ | ---------------- | | addCornJobV2 | 创建定时任务 | | setCronJobV2 | 修改定时任务 | | getCronJobListV2 | 查询定时任务列表 | | getCronJobInfoV2 | 查询定时任务详情 | | batchDeleteCronJob | 批量删除定时任务 |

API 详细说明

1) 创建定时任务

接口名称

addCornJobV2

功能描述

创建定时任务。

参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | ---------- | ------------- | ------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | dk | string | - | 是 | 设备 DeviceKey | | pk | string | - | 是 | 产品 ProductKey | | type | string | - | 是 | 定时任务类型（once: 执行一次，day-repeat: 每天重复，custom-repeat: 每周重复，multi-section: 多段执行，delay: 倒计时） | | timers | array | - | 是 | 定时任务列表（详见下方 CronJobTimer 字段说明） | | enabled | boolean | - | 否 | 任务状态（true 启动，false 停止） | | dayOfWeek | string | - | 否 | 重复周期：1 周一，2 周二，3 周三，4 周四，5 周五，6 周六，7 周日，多个使用英文逗号分隔；当 type 为 custom-repeat / multi-section（部分场景含 random）时必填 | | cacheTime | number | - | 否 | 下行缓存时间，单位秒，值范围：0-7776000 | | timeZone | string | - | 否 | 时区偏移量，格式：+-HH:mm，例如：+08:00 | | timeZoneId | string | - | 否 | 时区标识符，例如：Asia/Shanghai | | success | function | - | 是 | 成功回调 | | fail | function | - | 否 | 失败回调 | | complete | function | - | 否 | 结束回调 |

CronJobTimer 字段说明：

| 字段 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | -------------------------- | | time | string | 是 | 执行时间，格式 HH:mm:ss | | action | string | 是 | 物模型指令 JSON 字符串 | | delay | number | 是 | 延迟秒数（delay 类型必填） | | taskLogo | string | 是 | 任务图标 | | taskName | string | 是 | 任务名称 | | cacheTime | number | 是 | 下行缓存时间，单位秒 |

返回数据

• success(res)：接口成功响应。

示例代码

plugin.scheduledTask.addCornJobV2({
  dayOfWeek: '1',
  dk: 'device_key',
  enabled: true,
  pk: 'product_key',
  timers: [
    {
      time: '01:00:00',
      action: '[{"modelCode":"switch","modelName":"开关","modelType":"PROPERTY","dataType":"BOOL","value":true}]',
      delay: 0,
      taskLogo: '',
      taskName: '',
      cacheTime: 0
    }
  ],
  type: 'custom-repeat',
  success(res) {
    console.log(res)
  },
  fail(err) {
    console.log(JSON.stringify(err))
  },
  complete() {}
})

2) 修改定时任务

接口名称

setCronJobV2

功能描述

根据 ruleId 修改指定定时任务，可更新执行类型、执行动作、启停状态、重复周期、缓存时间与时区信息。

参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | ---------- | ------------- | ------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ruleId | string | - | 是 | 定时任务 ID | | dk | string | - | 是 | 设备 DeviceKey | | pk | string | - | 是 | 产品 ProductKey | | type | string | - | 是 | 定时任务类型（once: 执行一次，day-repeat: 每天重复，custom-repeat: 每周重复，multi-section: 多段执行，delay: 倒计时） | | timers | array | - | 是 | 定时任务列表（详见下方 CronJobTimer 字段说明） | | enabled | boolean | - | 否 | 任务状态（true 启动，false 停止） | | dayOfWeek | string | - | 是 | 重复周期：1 周一，2 周二，3 周三，4 周四，5 周五，6 周六，7 周日，多个使用英文逗号分隔；当 type 为 custom-repeat / multi-section（部分场景含 random）时使用该规则 | | cacheTime | number | - | 否 | 下行缓存时间，单位秒，值范围：0-7776000 | | timeZone | string | - | 否 | 时区偏移量，格式：+-HH:mm，例如：+08:00 | | timeZoneId | string | - | 否 | 时区标识符，例如：Asia/Shanghai | | success | function | - | 是 | 成功回调 | | fail | function | - | 否 | 失败回调 | | complete | function | - | 否 | 结束回调 |

CronJobTimer 字段说明：

| 字段 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | -------------------------- | | time | string | 是 | 执行时间，格式 HH:mm:ss | | action | string | 是 | 物模型指令 JSON 字符串 | | delay | number | 是 | 延迟秒数（delay 类型必填） | | taskLogo | string | 是 | 任务图标 | | taskName | string | 是 | 任务名称 | | cacheTime | number | 是 | 下行缓存时间，单位秒 |

返回数据

• success(res)：接口成功响应。

示例代码

plugin.scheduledTask.setCronJobV2({
  ruleId: 'rule_id',
  dayOfWeek: '1',
  dk: 'device_key',
  enabled: true,
  pk: 'product_key',
  timers: [
    {
      time: '01:00:00',
      action: '[{"modelCode":"switch","modelName":"开关","modelType":"PROPERTY","dataType":"BOOL","value":true}]',
      delay: 0,
      taskLogo: '',
      taskName: '',
      cacheTime: 0
    }
  ],
  type: 'custom-repeat',
  success(res) {
    console.log(res)
  },
  fail(err) {
    console.log(JSON.stringify(err))
  },
  complete() {}
})

3) 查询定时任务列表

接口名称

getCronJobListV2

功能描述

查询定时任务列表。

参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | -------- | -------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------- | | dk | string | - | 是 | 设备 deviceKey | | pk | string | - | 是 | 产品 productKey | | type | string | - | 否 | 定时任务类型。once: 执行一次，day-repeat: 每天重复，custom-repeat: 每周重复，multi-section: 多段执行，delay: 倒计时 | | page | number | - | 否 | 当前页码 | | pageSize | number | - | 否 | 每页条数 | | success | function | - | 是 | 接口调用成功的回调函数 | | fail | function | - | 否 | 接口调用失败的回调函数 | | complete | function | - | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |

返回数据

• success(res)：接口成功响应，res.data 为定时任务列表。

示例代码

plugin.scheduledTask.getCronJobListV2({
  dk: 'device_key',
  pk: 'product_key',
  type: 'once',
  page: 1,
  pageSize: 20,
  success(res) {
    console.log(res)
  },
  fail(err) {
    console.log(JSON.stringify(err))
  },
  complete() {}
})

4) 查询定时任务详情

接口名称

getCronJobInfoV2

功能描述

根据定时任务 ID 查询详情。

参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | -------- | -------- | ------ | ---- | ----------- | | ruleId | string | - | 是 | 定时任务 ID | | success | function | - | 是 | 成功回调 | | fail | function | - | 否 | 失败回调 | | complete | function | - | 否 | 结束回调 |

返回数据

• success(res)：接口成功响应，res.data 为定时任务详情。

示例代码

plugin.scheduledTask.getCronJobInfoV2({
  ruleId: 'rule_id',
  success(res) {
    console.log(res)
  },
  fail(err) {
    console.log(JSON.stringify(err))
  },
  complete() {}
})

5) 批量删除定时任务

接口名称

batchDeleteCronJob

功能描述

按 ruleId 列表批量删除定时任务。

参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | ---------- | -------- | ------ | ---- | ---------------- | | ruleIdList | string[] | - | 是 | 定时任务 ID 列表 | | success | function | - | 是 | 成功回调 | | fail | function | - | 否 | 失败回调 | | complete | function | - | 否 | 结束回调 |

返回数据

• success(res)：接口成功响应。

示例代码

plugin.scheduledTask.batchDeleteCronJob({
  ruleIdList: ['rule_1', 'rule_2'],
  success(res) {
    console.log(res)
  },
  fail(err) {
    console.log(JSON.stringify(err))
  },
  complete() {}
})