适用于 App Engine SDK 工具的 cron.xml 参考

使用 cron.xml 文件为您的应用定义安排任务。

如需详细了解安排任务,包括如何测试、部署或删除 Cron 作业,请参阅使用 Cron 安排任务

示例

下面是一个 cron.xml 文件示例:

<?xml version="1.0" encoding="UTF-8"?>
<cronentries>
  <cron>
    <url>/recache</url>
    <description>Repopulate the cache every 2 minutes</description>
    <schedule>every 2 minutes</schedule>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
    <target>version-2</target>
  </cron>
</cronentries>

如需描述该格式的 XSD,请查看 SDK 中的 docs/cron.xsd 文件。

语法

cron.xml 文件和 appengine-web.xml 文件应位于应用的 WEB-INF 目录中,cron.xml 可为您的 Java 8 应用配置计划任务。

Cron 作业定义

元素 说明
<description> 可选。该说明显示在 Cloud Console 和开发服务器的管理界面中。
<retry-parameters> 可选。如果 Cron 作业的请求处理程序返回的 HTTP 状态代码不在 200-299(含 200 和 299)范围内,则 App Engine 会认为该作业失败。默认情况下不会重试失败的作业。您可以通过在配置文件中包含 retry_parameters 块,促使系统重试失败的作业。

如需了解详情,请参阅 Cron 重试部分。

<schedule> 必需。定义 Cron 作业的运行时间表,请参阅下面的语法
<target>

target 字符串将添加到应用的主机名之前。该字符串通常是服务的名称。Cron 作业将路由到被配置为接收流量的指定服务的相应版本。

如果系统找不到为 target 指定的服务名称,则 Cron 请求会路由到 default 服务,或者配置为接收流量的应用版本。如需详细了解如何路由,请参阅请求的路由方式

<timezone> timezone 应该是标准 zoneinfo 时区名称。如果未指定时区,作业将按照 UTC(也称为 GMT)运行。
<url> 必需。 <url> 字段只是应用中的一个网址。如果 <url> 元素包含特殊 XML 字符 &<>'",则应对其进行转义。

定义 Cron 作业 schedule

Cron 作业按周期性间隔进行安排,并使用类似英文中的简单时间格式指定。您可以定义时间表,以便让您的作业每天运行多次,或在特定的日子和月份运行。

小于一天的时间间隔

使用小于一天的时间间隔,按重复性时间表每天多次运行作业。您可以定义结束时间间隔或开始时间间隔:

  • 结束时间间隔:定义一次作业的“结束时间”与下一次作业的开始时间之间的时间间隔,其中“结束时间”是指作业完成或超时的那个时间点。Cron 服务从 00:00 开始,全天(24 小时)以这种间隔运行作业,并在两个作业之间等待指定的时长。

    示例:对于 every 5 minutes 时间表,作业每天以 5 分钟为间隔运行。如果按此时间表运行的一个作业实例在 02:01 完成,则下一个作业将等待 5 分钟,于 02:06 再次开始运行。

  • 开始时间间隔:定义 Cron 服务启动每个作业的固定时间间隔。与结束时间间隔不同,如果采用开始时间间隔,则每次运行作业时不会考虑前一作业完成或超时的时间。您可以设置要运行作业的时间范围,或者在从 00:00 开始的全天(24 小时)内运行作业。

    由于严格限制了作业的开始时间,因此,如果作业的某个实例的运行时间超过了定义的时间间隔,则 Cron 服务可能会跳过作业。如果前一个作业尚未完成或超时,则系统会跳过间隔中的一个开始时间。

    示例:对于 every 5 minutes from 10:00 to 14:00 时间表,第一个作业在 10:00 开始运行,然后每 5 分钟开始运行下一个作业。如果第一个作业运行 7 分钟,则会跳过 10:05 的作业,因此,Cron 服务直到 10:10 才会运行该作业的另一个实例。

自定义时间间隔

您可以使用自定义时间间隔来定义时间表,让您的作业在一个或多个选定月份中的一个或多个选定日期每天运行一次。按自定义时间表运行的作业会全年运行,而且仅在选定月份和日期的特定时间运行。

示例:对于 1,2,3 of month 07:00 时间表,作业在每月前三天的 07:00 各运行一次。

schedule 的重要注意事项:

  • 您必须决定是使用小于一天的时间间隔还是自定义时间间隔。不能混用各种间隔类型的元素。例如,<schedule>every 6 hours mon,wed,fri</schedule> 这一时间表定义是无效的。
  • 任何时间都只能运行一个作业实例。Cron 服务被设计为提供“至少一次”传送;也就是说,如果安排了某个作业,则 App Engine 会至少发送一次作业请求。在极少数情况下,可能会请求同一作业的多个实例,因此,您的请求处理程序应该具有幂等性,并且您的代码应确保在发生这种情况时不会产生任何有害的副作用。

设置 schedule 的格式

如需指定作业的运行时间,则必须使用以下语法定义 schedule 元素:

<schedule>[TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]</schedule>

选择一种间隔类型来定义 schedule 元素:

结束时间间隔
  • [TYPE]:每日间隔必须包含 every 前缀。

    示例:<schedule>every 12 hours</schedule>

  • [INTERVAL_VALUE]:整数值及相应的时间单位。时间单位的有效值包括:
    • minutesmins
    • hours
  • [INTERVAL_SCOPE]:不适用。如需设置作业开始运行的具体时间或运行时间范围,请参阅开始时间间隔自定义时间间隔的语法。
结束时间间隔示例
以下示例可帮助您了解如何定义使用结束时间间隔的作业时间表:
  • 每天 00:00 开始运行,每两个作业之间等待 5 分钟。每次作业结束后,Cron 服务等待 5 分钟后再运行下一次作业:
    <schedule>every 5 minutes</schedule>
  • 每天 00:00 开始运行,每两次作业之间等待 30 分钟。每个作业结束后,Cron 服务等待 30 分钟后再运行下一个作业:
    <schedule>every 30 mins</schedule>
开始时间间隔
  • [TYPE]:每日间隔必须包含 every 前缀。

    示例:<schedule>every 12 hours</schedule>

  • [INTERVAL_VALUE]:整数值及相应的时间单位。时间单位的有效值包括:
    • minutesmins
    • hours
  • [INTERVAL_SCOPE] 指定对应于 [INTERVAL_VALUE] 的子句。您可以自定义时间范围,或使用 24 小时 synchronized 选项。
    • 添加 from [HH:MM] to [HH:MM] 子句,以定义作业开始运行的具体时间和运行时间范围。

      您必须以 24 小时制 (HH:MM) 指定时间值,其中:

      • HH 是从 0023 的整数。
      • MM 是从 0059 的整数。
    • 使用 synchronized 指定 24 小时时间范围 (from 00:00 to 23:59),此范围按 [INTERVAL_VALUE] 值均分。

      重要提示:24 必须能被 [INTERVAL_VALUE] 整除,否则会发生错误。[INTERVAL_VALUE] 的有效值包括:1234681224

开始时间间隔示例
以下示例可帮助您了解如何定义使用开始时间间隔的作业时间表:
  • 每天 10:00 至 14:00,每 5 分钟运行一次:
    <schedule>every 5 minutes from 10:00 to 14:00</schedule>
  • 每天 08:00 至 16:00,每小时运行一次:
    <schedule>every 1 hours from 08:00 to 16:00</schedule>
  • 每天从 00:00 开始,每两小时运行一次:
    <schedule>every 2 hours synchronized</schedule>
自定义时间间隔
  • [TYPE]:自定义时间间隔可以包含 every 前缀以定义重复性间隔,或者您也可以定义一个月中特定日期的列表:
    • 如需定义重复性间隔,您可以使用 every 前缀。

      示例:

      <schedule>every day 00:00</schedule>
      <schedule>every monday 09:00</schedule>

    • 如需定义特定的天数,您必须使用序数。有效值为一个月的第一天到该月的最后一天,例如:
      • 1stfirst
      • 2ndsecond
      • 3rdthird
      • 一直到:31stthirtyfirst

      示例:

      <schedule>1st,3rd tuesday</schedule>
      <schedule>2nd,third wednesday of month 09:00</schedule>

  • [INTERVAL_VALUE]:自定义时间间隔包含您希望运行作业的特定天数或星期几的列表。该列表中的值必须用英文逗号隔开,该列表可以包含以下任何一种值:
    • 一个月中日期的整数值,最多 31 天,例如:
      • 1
      • 2
      • 3
      • 一直到:31
    • 混合使用以下任何完整值或简写值的日期名称:
      • mondaymon
      • tuesdaytue
      • wednesdaywed
      • thursdaythu
      • fridayfri
      • saturdaysat
      • sundaysun
      • 使用 day 指定一周中的所有日期。

    示例:

    <schedule>2nd monday,thu</schedule>
    <schedule>1,8,15,22 of month 09:00</schedule>
    <schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>

  • [INTERVAL_SCOPE]:指定对应于所指定 [INTERVAL_VALUE] 的子句。自定义时间间隔可以包括 of [MONTH] 子句,用于指定一年中的一个月,或以逗号分隔列表的形式指定多个月。您还必须定义希望运行作业的特定时间,例如:of [MONTH] [HH:MM]

    默认情况下,如果不包括 of 子句,则每月均按自定义时间间隔运行。

    • [MONTH]:必须使用英文逗号分隔列表来指定月份,并且可以混用以下完整值或简写值:
      • januaryjan
      • februaryfeb
      • marchmar
      • aprilapr
      • may
      • junejun
      • julyjul
      • augustaug
      • septembersep
      • octoberoct
      • novembernov
      • decemberdec
      • 使用 month 指定一年中的所有月份。
    • [HH:MM]:必须以 24 小时制 (HH:MM) 指定时间值,其中:
      • HH 是从 0023 的整数。
      • MM 是从 0059 的整数。
    • 示例:

      <schedule>1st monday of sep,oct,nov 09:00</schedule>
      <schedule>1 of jan,april,july,oct 00:00</schedule>

自定义时间间隔示例
以下示例可帮助您了解如何定义使用自定义时间间隔的作业时间表:
  • 每天 00:00 运行:
    <schedule>every day 00:00</schedule>
  • 每周一 09:00 运行:
    <schedule>every monday 09:00</schedule>
  • 在 3 月第二个星期三的 17:00 运行一次:
    <schedule>2nd wednesday of march 17:00</schedule>
  • 在 5 月运行六次。在前两周的每周一、周三和周五 10:00 各运行一次:
    <schedule>1st,second mon,wed,fri of may 10:00</schedule>
  • 每周运行一次。从每个月的第一天开始,每七天在 09:00 运行一次:
    <schedule>1,8,15,22 of month 09:00</schedule>
  • 每隔一周运行一次。在每个月的第一个和第三个星期一的 04:00 各运行一次:
    <schedule>1st,third monday of month 04:00</schedule>
  • 每年运行三次。在 9 月、10 月和 11 月第一个星期一的 09:00 各运行一次:
    <schedule>1st monday of sep,oct,nov 09:00</schedule>
  • 每个季度运行一次。在 1 月、4 月、7 月和 10 月第一天的 00:00 运行一次:
    <schedule>1 of jan,april,july,oct 00:00</schedule>

Cron 重试

如果 Cron 作业的请求处理程序返回的状态代码不在 200-299(含 200 和 299)范围内,则 App Engine 会认为该作业失败。默认情况下不会重试失败的作业。您可以在配置文件中添加 <retry-parameters> 块,促使系统重试失败的作业。

下面是一个 cron.xml 文件示例,其中包含一个 Cron 作业,该作业配置为最多重试五次(默认值),初始退避时间为 2.5 秒,每次加倍。

<cronentries>
  <cron>
    <url>/retry</url>
    <description>Retry on jsdk</description>
    <schedule>every 10 minutes</schedule>
    <retry-parameters>
      <min-backoff-seconds>2.5</min-backoff-seconds>
      <max-doublings>5</max-doublings>
    </retry-parameters>
  </cron>
</cronentries>

Cron 重试语法

下表介绍了重试参数。

元素 说明
<job-retry-limit> 失败的 Cron 作业的重试次数上限,不超过 5。如果指定了 <job-age-limit>,则 App Engine 会重试 Cron 作业,直到同时达到这两个限制为止。如果参数中省略了此元素,则该限制默认设置为 5。
<job-age-limit> 重试失败的 Cron 作业的时间限制,从首次运行 Cron 作业开始计算。该值是一个数字,后跟一个时间单位,其中 s 表示秒,m 表示分钟,h 表示小时,d 表示天。例如,值 5d 表示仅限在 Cron 作业首次尝试执行后的五天内进行重试。如果指定了 <job-retry-limit>,则 App Engine 会重试 Cron 作业,直到同时达到这两个限制为止。
<min-backoff-seconds> Cron 作业失败后重试该作业之前等待的秒数下限。
<max-backoff-seconds> Cron 作业失败后重试该作业之前等待的秒数上限。
<max-doublings> 在增加量变为常量之前,失败的 Cron 作业重试之间的时间间隔将加倍的最大次数。该常量为:2**(max_doublings - 1) * min_backoff

Cron 请求

请求标头

来自 Cron 服务的请求将包含 HTTP 标头:

X-Appengine-Cron: true

此标头和其他标头由 App Engine 在内部设置。如果客户端发送此类标头,它们会从请求中移除。来自旧版应用的已登录管理员的请求例外,管理员可以设置标头用于测试目的。

发起 IP 地址

App Engine 从 IP 地址 0.1.0.1 发出 Cron 请求。

时限

Cron 超时截止时间取决于为您的应用配置的实例类别和扩缩类型:

自动扩缩
超时大约为 10 分钟。
基本扩缩和手动扩缩
超时最长可达 24 小时。

如需了解详情,请参阅实例的管理方式

限制

免费应用最多可以安排 20 个计划任务。付费应用最多可以安排 250 个计划任务。

开发服务器中的 Cron 支持

开发服务器不会自动运行您的 cron 作业。您可以使用本地桌面的 Cron 或计划任务界面通过 curl 或类似工具触发作业的网址。

部署 Cron 作业

您可以使用 appcfg.sh 工具将 Cron 作业部署到 App Engine。

选项 1:上传整个应用

要上传整个应用(同时还会使用来自 cron.xml 文件的条目更新 Cron 服务),请运行以下命令:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
选项 2:仅上传 Cron 更新

如果只需更新 Cron 配置,而不上传应用的其余部分,请运行以下命令:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]

删除所有 cron 作业

如需删除所有 Cron 作业,请执行以下操作:

  1. cron.xml 文件的内容修改为:

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries/>
    
  2. cron.xml 文件部署到 App Engine。

Cloud Console 中的 Cron 支持

Cloud Console“任务队列”页面包含一个标签页,用于显示正在运行 Cron 作业的任务。

您还可以访问“日志”页面,查看添加或移除 Cron 作业的时间。