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 at a given time of day. A URL invoked by cron is subject to the same limits and quotas as a normal HTTP request, including the request time limit.
An application can have up to 20 scheduled tasks.
A cron.xml
file in the WEB-INF
directory of your application (alongside appengine-web.xml
) controls cron for your Java application. The following is an example cron.xml
file:
<?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 of month 08:30</schedule> <timezone>America/New_York</timezone> </cron> </cronentries>
For an XSD describing the format, check the file docs/cron.xsd
in the SDK.
A cron.xml
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>
and a <timezone>
. The description will be visible in the admin console.
The url
url field is just a URL in your application. The format of the schedule
field is covered more in The Schedule Format.
The timezone should be the name of a standard zoneinfo time zone name. If you don't specify a timezone, jobs run in UTC (also known as GMT).
Cron schedules are specified using a simple English-like format.
The following are examples of schedules:
every 5 minutes every 12 hours 2nd,third mon,wed,thu of march 17:00 every monday of month 09:00 1st monday of sep,oct,nov 17: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)
, where N is a number and hours or minutes specifies the unit of time. The shortest time between runs of a task that can be specified is 1 minute.
If you want more specific timing, you can specify the schedule as:
("every"|ordinal) (days) "of" (monthspec) (time)
The brackets are for illustration only, and quotes indicate a literal.
Where:
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 read about restricting URLs at Security and Authentication. An example you would use in web.xml
to restrict everything starting with /cron/
to admin-only is:
<security-constraint> <web-resource-collection> <url-pattern>/cron/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>admin</role-name> </auth-constraint> </security-constraint>
For more on the format of web.xml
, see the documentation on the deployment descriptor.
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.
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.xml
. 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.xml file to just contain:
<?xml version="1.0" encoding="UTF-8"?> <cronentries/>
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.