English
Skip to page content Skip to main navigation

e.g. "templates" or "datastore"

# Scheduled Tasks With Cron for Python

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.

- About cron.yaml
- The Schedule Format
- Securing URLs for Cron
- Uploading Cron Jobs
- Cron Support in the Admin Console
- Cron Support in the Development Server

## About cron.yaml

A `cron.yaml` file in the root directory of your application (alongside `app.yaml`) configures scheduled tasks for your Python 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

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` and a `timezone`. The description will be 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 Schedule Format

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 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)`, 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:

- ordinal specifies a comma separated list of "1st", "first" and so forth (both forms are ok)
- days specifies a comma separated list of days of the week (for example, "mon", "tuesday", with both short and long forms being accepted); "every day" is equivalent to "every mon,tue,wed,thu,fri,sat,sun"
- monthspec specifies a comma separated list of month names (for example, "jan", "march", "sep"); if omitted, implies every month
- time specifies the time of day, as HH:MM in 24 hour time.

## Securing URLs for Cron

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: python
    api_version: 1

    handlers:
    - url: /report/weekly
      script: reports.py
      login: admin

For more information see Python Application Configuration: 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.

## Uploading Cron Jobs

You can use `appcfg.py` to upload cron jobs and view information about the defined cron jobs. When you upload your application to App Engine using `appcfg.py 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.py update_cron`.

To delete all cron jobs, change the `cron.yaml` file to just contain:

    cron:

You can display the parsed version of your cron jobs, including the times the jobs will run, using the `appcfg.py cron_info` command.

If you want `appcfg.py cron_info` to correctly handle timezones you have specified, install the pytz package.

## Cron Support in the Admin Console

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.

## Cron Support in the Development Server

When using the Python SDK, the dev_appserver has an admin interface that allows you to view cron jobs at `/_ah/admin/cron`.

The development server doesn't automatically run your cron jobs. You can use your local desktop's cron or scheduled tasks interface to trigger the URLs of your jobs with curl or a similar tool.