使用 Java 8 版 Cron 安排任务

借助 App Engine Cron 服务,您可以配置在指定时间或按固定时间间隔执行的定期计划任务。这些任务通常称为“Cron 作业”。这些 Cron 作业由 App Engine Cron 服务自动触发。例如,您可以使用 Cron 作业每天发送一封电子邮件报告,或者每 10 分钟更新一次缓存数据,每小时刷新一次摘要信息。

Cron 作业会按计划对网址发出 HTTP GET 请求。调用网址的处理程序后,即执行相应逻辑。Cron 作业请求与推送任务队列请求受相同的限制约束。

准备工作

要部署或更新计划,您的帐号需要拥有以下某个 IAM 角色:

  • 所有者
  • Editor

您可以在 Google Cloud Console 中的 IAM 页面上设置权限。

创建 Cron 作业

  1. 在应用的 WEB-INF/ 目录中创建 cron.xml 文件(以及 appengine-web.xml)。
  2. 在此文件中添加一个或多个 <cron> 条目,并定义作业的必要元素,包括必需的 <url><schedule> 元素。

    以下示例将创建一个每天执行的基本 Cron 作业:

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries>
      <cron>
        <url>/tasks/summary</url>
        <target>beta</target>
        <description>daily summary job</description>
        <schedule>every 24 hours</schedule>
      </cron>
    </cronentries>
    

    您可以视情况将目标 (target) 指定为服务/版本的名称。如果指定该元素,请将其添加到应用的主机名之前,以将作业路由到该服务/版本。如果未指定目标,则作业将在为流量配置的 default 服务版本中运行。

  3. 为 Cron 作业网址创建处理程序。处理程序应执行您想安排的任何任务,并使用 200 到 299(含)之间的 HTTP 状态代码进行响应,以表示其运行成功。或者,也可以返回其他状态代码,以用于重试 Cron 作业

处理程序可以像应用中的 Servlet 一样简单。web.xml 中的 Servlet 网址映射应与 Cron 作业网址相同。详细了解 cron.xml 语法和选项

在开发服务器中测试 Cron 作业

本地开发服务器不会自动运行 Cron 作业。您可以直接向 Cron 作业网址发出请求,以测试其功能。您可以使用本地 Cron 或计划任务界面,通过 curl 或类似工具触发作业的网址。

重试运行失败的 Cron 作业

如果 Cron 作业的请求处理程序返回的状态代码不在 200-299(含)范围内,则 App Engine 认为该作业失败。默认情况下,除非返回 503 状态代码,否则不会重试运行失败的作业。如返回 503 状态代码,则每分钟重试一次,直到运行成功或返回 200-299 状态代码。

要设置重新尝试执行失败的作业,请执行以下操作:

  1. cron.xml 文件中添加 retry-parameters 块。
  2. 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 重试选项

部署 Cron 作业

选项 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。

保护 Cron 的网址

您可以防止用户访问计划任务使用的网址,仅限管理员帐号访问这些网址。计划任务可以访问仅限管理员访问的网址。您可以阅读安全和身份验证,了解限制网址访问权限的相关信息。您可以在 web.xml 中使用代码来限制只有管理员能够访问以 /cron/ 开头的所有内容,此类代码的示例如下:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>cron</web-resource-name>
        <url-pattern>/cron/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>

如需详细了解 web.xml 的格式,请参阅有关部署描述符的文档。

要测试 Cron 作业,请以管理员身份登录,然后在浏览器中访问处理程序的网址。

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

X-Appengine-Cron: true

X-Appengine-Cron 标头由 Google App Engine 在内部设置。如果您的请求处理程序找到此标头,则可以确信该请求是 Cron 请求。如果该标头出现在应用的外部用户请求中,将该标头会被删除(由允许设置测试标头的应用管理员登录并发出的请求除外)。

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

调用 Google Cloud 端点

您无法在 Cron 作业的 url 字段中指定 Google Cloud Endpoints 端点。如果您希望 Cron 作业调用 Google Cloud Endpoints 端点,请向应用中的处理程序处理的目标发出请求,并通过处理程序代码调用端点类和方法。

在 Cloud Console 中查看 Cron 作业

您可以在 Cloud Console 的 Cron 作业页面上查看已安排的 Cron 作业。

您还可以查看日志,以了解添加或移除 Cron 作业的时间。

了解详情

如需详细了解如何定义 Cron 作业,请参阅 cron.xml 参考文档