# 定时触发器

> 该功能需开发者工具 1.02.1811270 及以上版本方可使用
> 
> 从开发者工具 1.02.1910182 开始，新上传的定时触发器内支持使用云调用

如果云函数需要定时 / 定期执行，也就是定时触发，我们可以使用云函数定时触发器。配置了定时触发器的云函数，会在相应时间点被自动触发，函数的返回结果不会返回给调用方。

在需要添加触发器的云函数目录下新建文件 `config.json`，格式如下：

```json
{
  // triggers 字段是触发器数组，目前仅支持一个触发器，即数组只能填写一个，不可添加多个
  "triggers": [
    {
      // name: 触发器的名字，规则见下方说明
      "name": "myTrigger",
      // type: 触发器类型，目前仅支持 timer (即 定时触发器)
      "type": "timer",
      // config: 触发器配置，在定时触发器下，config 格式为 cron 表达式，规则见下方说明
      "config": "0 0 2 1 * * *"
    }
  ]
}
```

字段规则：

- 定时触发器名称 (name)：最大支持 60 个字符，支持 `a-z`, `A-Z`, `0-9`, `-` 和 `_`。必须以字母开头，且一个函数下不支持同名的多个定时触发器。
- 定时触发器触发周期 (config)：指定的函数触发时间。填写自定义标准的 cron 表达式来决定何时触发函数。有关 cron 表达式的更多信息，请参考下面的内容。

### Cron 表达式

Cron 表达式有七个必需字段，按空格分隔。

| 第一位 | 第二位 | 第三位 | 第四位 | 第五位 | 第六位 | 第七位 |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| 秒     | 分钟   | 小时   | 日     | 月     | 星期   | 年     |

其中，每个字段都有相应的取值范围：

| 字段 | 值                                                           | 通配符  |
| ---- | ------------------------------------------------------------ | ------- |
| 秒   | 0-59 的整数                                                  | , - * / |
| 分钟 | 0-59 的整数                                                  | , - * / |
| 小时 | 0-23 的整数                                                  | , - * / |
| 日   | 1-31 的整数（需要考虑月的天数）                              | , - * / |
| 月   | 1-12 的整数 或 JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC | , - * / |
| 星期 | 0-6 的整数 或 SUN,MON,TUE,WED,THU,FRI,SAT；其中 0 指周日，1 指周一，依次类推，6 指周六 | , - * / |
| 年   | 1970~2099 的整数                                             | , - * / |

**通配符**

| 通配符     | 含义                                                         |
| ---------- | ------------------------------------------------------------ |
| , (逗号)   | 代表取用逗号隔开的字符的并集。例如：在“小时”字段中 1,2,3 表示 1 点、2 点和 3 点 |
| - (破折号) | 包含指定范围的所有值。例如：在“日”字段中，1-15 包含指定月份的 1 号到 15 号 |
| * (星号)   | 表示所有值。在“小时”字段中，* 表示每个小时                   |
| / (正斜杠) | 指定增量。在“分钟”字段中，输入 1/10 以指定从第一分钟开始的每隔十分钟重复。例如，第 11 分钟、第 21 分钟和第 31 分钟，依此类推 |

**注意事项**

- 在 Cron 表达式中的“日”和“星期”字段同时指定值时，两者为“或”关系，即两者的条件分别均生效。
- 触发器规则的时区为 UTC+8
- 由于网络环境不稳定，微信可能会多次推送同一条消息。建议将消息 ID 作为唯一标识做好去重，防止业务逻辑重复执行。

**示例**

下面展示了一些 Cron 表达式和相关含义的示例：

- `*/5 * * * * * *` 表示每 5 秒触发一次
- `0 0 2 1 * * *` 表示在每月的 1 日的凌晨 2 点触发
- `0 15 10 * * MON-FRI *` 表示在周一到周五每天上午 10:15 触发
- `0 0 10,14,16 * * * *` 表示在每天上午 10 点，下午 2 点，4 点触发
- `0 */30 9-17 * * * *` 表示在每天上午 9 点到下午 5 点内每半小时触发
- `0 0 12 * * WED *` 表示在每个星期三中午 12 点触发

### 环境信息

在云函数内，可以通过 `getWXContext().SOURCE === 'wx_trigger'` 判断调用来源是触发器。（附：[所有调用来源列表](/miniprogram/dev/wxcloudservice/wxcloud/reference-sdk-api/utils/Cloud.getWXContext)）

在[下一章节](mechanism)，我们一起了解下云函数的运行机制。