Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
The App Engine Cron Service allows you to configure regularly scheduled tasks that operate at defined times or regular intervals. These tasks are commonly known as cron jobs. These cron jobs are automatically triggered by the App Engine Cron Service. For instance, you might use this to send out a report email on a daily basis, to update some cached data every 10 minutes, or to update some summary information once an hour.
A cron job will invoke a URL, using an HTTP GET request, at a given time of day. An HTTP request invoked by cron can run for up to 10 minutes, but is subject to the same limits as other HTTP requests.
An application can have up to 20 scheduled tasks.
A cron.yaml
file in the WEB-INF
directory of your application (alongside app.yaml
) configures scheduled tasks for your application. The following is an example cron.yaml
file:
cron: - description: daily summary job url: /tasks/summary schedule: every 24 hours - description: monday morning mailout url: /mail/weekly schedule: every monday 09:00 timezone: Australia/NSW - description: new daily summary job url: /tasks/summary schedule: every 24 hours target: version-2
The syntax of cron.yaml
is the YAML format. For more information about this syntax, see the YAML website for more information.
A cron.yaml
file consists of a number of job definitions. A job definition must have a url
and a schedule
. You can also optionally specify a description
, timezone
, and a target
. The description is visible in the Admin Console and the development server's admin interface.
The url
field specifies a URL in your application that will be invoked by the Cron Service. See Securing URLs for Cron for more. The format of the schedule field is covered in The Schedule Format.
The timezone should be the name of a standard zoneinfo time zone name. If you don't specify a timezone, the schedule will be in UTC (also known as GMT).
The target
specifies the version of your application on which to invoke the URL. See Java Application Configuration Using app.yaml for more information about application versions.
Cron schedules are specified using a simple English-like format.
The following are examples of schedules:
every 12 hours every 5 minutes from 10:00 to 14:00 2nd,third mon,wed,thu of march 17:00 every monday 09:00 1st monday of sep,oct,nov 17:00 every day 00:00
If you don't need to run a recurring job at a specific time, but instead only need to run it at regular intervals, use the form:
every N (hours|mins|minutes) ["from" (time) "to" (time)]
The brackets are for illustration only, and quotes indicate a literal.
By default, an interval schedule starts the next interval after the last job has completed. If a from...to clause is specified, however, the jobs are scheduled at regular intervals independent of when the last job completed. For example:
every 2 hours from 10:00 to 14:00
This schedule runs the job three times per day at 10:00, 12:00, and 14:00, regardless of how long it takes to complete. You can use the literal "synchronized" as a synonym for from 00:00 to 23:59:
every 2 hours synchronized
If you want more specific timing, you can specify the schedule as:
("every"|ordinal) (days) ["of" (monthspec)] (time)
Where:
A cron handler is just a normal handler defined in app.yaml
. You can prevent users from accessing URLs used by scheduled tasks by restricting access to administrator accounts. Scheduled tasks can access admin-only URLs. You can restrict a URL by adding login: admin
to the handler configuration in app.yaml
.
An example might look like this in app.yaml
:
application: hello-cron version: 1 runtime: java api_version: 1 handlers: - url: /report/weekly servlet: mysite.server.CronServlet login: admin
Note: While cron jobs can use URL paths restricted with login: admin
, they cannot use URL paths restricted with login: required
.
For more information see Java Application Configuration Using app.yaml: Requiring Login or Administrator Status.
To test a cron job, sign in as an administrator and visit the URL of the handler in your browser.
Requests from the Cron Service will also contain a HTTP header:
X-AppEngine-Cron: true
If you wish to ensure that only cron requests can trigger your handler, you should check for that header.
If the target
parameter has been set for a job, the request is sent to the specified version. Otherwise Cron requests are sent to the default version of the application.
You can use AppCfg
to upload cron jobs. When you upload your application to App Engine using AppCfg update
, the Cron Service is updated with the contents of cron.yaml
. You can update just the cron configuration without uploading the rest of the application using AppCfg update_cron
.
To delete all cron jobs, change the cron.yaml file to just contain:
cron:
The Admin Console allows you to view the state of your cron jobs. Select the "Cron Jobs" link from the side menu to view the state of the jobs, including the last time the job was run and the result of the job.
You can also see when cron jobs are added or removed by selecting the "Admin Logs" page from the Admin Console menu.
The dev appserver doesn't automatically run your cron jobs. You can use your local desktop's cron or scheduled tasks interface to hit the URLs of your jobs with curl or a similar tool.