定时任务
###############

服务概述
==========

定时任务服务可以用来定期触发您的应用执行一些后台任务，像定期清理和备份 MySQL 表中的数据、发送邮件通知等。定时任务的执行以 HTTP 方式触发，触发后真正执行的是您在应用中定义的 HTTP 回调函数。

+ 任务执行的方式是 HTTP 调用（GET 方法），执行时间最长为 *1800 秒* 。
+ 任务执行存在一定的时间误差，最大不超过 *10 秒* 。
+ 任务不分应用版本，但只对默认版本生效，当切换代码默认版本时对应版本的定时任务会被激活。
+ 任务的时间间隔粒度为分钟。
+ 普通应用最大可以并发执行 12 个定时任务。多出的任务将不能被执行。

如何配置
=============

添加任务
----------

**通过 Web 页面**

你可以进入『新浪云／定时任务』页面，点击『新建定时任务』添加任务。

**通过 config.yaml  配置文件**

您也可以在应用的配置文件 `config.yaml` 中添加任务。任务的执行状态可在定时任务的 Web 管理页面看到。

编辑 *config.yaml* 文件，增加 *cron* 段，例如：   ::

    cron:
    - description: cron_test
      url: /cron/make
      schedule: "*/5 * * * *"

上面的示例添加了一个定时任务，该任务每 5 分钟调用 `http:// 应用名.sinaapp.com/cron/make` 一次。

每个定时任务的描述可以包含以下字段：

- url

  任务触发时调用的 url。只需写相对 url 即可。例如 `/relative/url/to/cron` 。

- schedule

  任务描述，也就是何时执行这个任务，支持 unix crontab 语法。unix crontab 的语法如下： ::

        <分钟> <小时> <日> <月份> <星期>

  - *分钟* 值从 0 到 59。
  - *小时* 值从 0 到 23。
  - *日* 值从 1 到 31。
  - *月* 值从 1 到 12。
  - *星期* 值从 0 到 6, 0 代表星期日。

  此外为了更灵活，unix crontab 语法还支持：

  - 时间范围可以用连字符给出，多个时间范围可以用逗号隔开。
  - 星号可以作为通配符。
  - 空格用来分开字段。
  - 除号可以用作指定每隔一段时间执行一次。

  例如下面一行将会指定任务在夏天（六、七、八月）之外的每周周一到周五的上午 9 点到下午 4 点之间每 5 分钟执行一次任务。 ::

         */5 9-16 * 1-5,9-12 1-5

  特殊语法字符串：

  ======================= ======================================================== ============
  字符串                  含义                                                     等价于
  ======================= ======================================================== ============
  @yearly 或 @annually    每年一月一号运行                                         0 0 0 1 1 *
  @monthly                每月一号运行                                             0 0 0 1 * *
  @weekly                 每周日的凌晨零点运行                                     0 0 0 * * 0
  @daily 或 @midnight     每天夜里凌晨零点运行                                     0 0 0 * * *
  @hourly                 每个整点运行                                             0 0 * * * *
  @every <时间间隔>       每隔一个固定的时间间隔运行，间隔时间由 duration 指定，
                          比如 ``@every 25m`` 表示每 25 分钟运行一次，
                          ``@every 1h30m`` 表示每 1 小时 30 分钟运行一次。
  ======================= ======================================================== ============


  更多范例和高级配置方法请参见： `man 5 crontab <http://man.he.net/man5/crontab>`_ 。

- description

  可选。任务的说明，默认为空。

- timezone

  可选。任务执行的时间采用的时区，默认为 *Asia/Shanghai* ，支持标准的时区名称格式，更多时区名称参见： https://en.wikipedia.org/wiki/List_of_tz_database_time_zones 。

- login

  可选。HTTP 基础认证设置，格式： `用户名 @密码`

更多范例： ::

   cron:
   - url: /see/the/scenes/of/Los_Angeles
     schedule: "0 4 * * *"
     timezone: "America/Los_Angeles"
     description: "在洛杉矶时间的每天凌晨 4 点执行"
   - url: /hearbeat
     schedule: "*/5 * * * *"
     description: "每 5 分钟执行一次"
   - url: /go/to/work
     schedule: "0 8 * * 1-5"
     description: "在工作日的每天早上 8 点执行"

删除任务
----------

在管理页面中点击删除，或者删除 *config.yaml* 中对应的任务描述段即可。