| title | description | services | documentationcenter | author | manager | editor | ms.assetid | ms.service | ms.workload | ms.tgt_pltfrm | ms.devlang | ms.topic | ms.date | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
How to Build Complex Schedules and Advanced Recurrence with Azure Scheduler |
How to Build Complex Schedules and Advanced Recurrence with Azure Scheduler |
scheduler |
.NET |
derek1ee |
kevinlam1 |
5c124986-9f29-4cbc-ad5a-c667b37fbe5a |
scheduler |
infrastructure-services |
na |
dotnet |
article |
08/18/2016 |
deli |
At the heart of an Azure Scheduler job is the schedule. The schedule determines when and how the Scheduler executes the job.
Azure Scheduler allows you to specify different one-time and recurring schedules for a job. One-time schedules fire once at a specified time – effectively, they are recurring schedules that execute only once. Recurring schedules fire on a predetermined frequency.
With this flexibility, Azure Scheduler lets you support a wide variety of business scenarios:
- Periodic data cleanup – e.g., every day, delete all tweets older than 3 months
- Archival – e.g., every month, push invoice history to backup service
- Requests for external data – e.g., every 15 minutes, pull new ski weather report from NOAA
- Image processing – e.g. every weekday, during off-peak hours, use cloud computing to compress images uploaded that day
In this article, we walk through example jobs that you can create with Azure Scheduler. We provide the JSON data that describes each schedule. If you use the Scheduler REST API, you can use this same JSON for creating an Azure Scheduler job.
The many examples in this topic illustrate the breadth of scenarios that Azure Scheduler supports. Broadly, these examples illustrate how to create schedules for many behavior patterns, including the ones below:
- Run once at a particular date and time
- Run and recur a number of explicit times
- Run immediately and recur
- Run and recur every n minutes, hours, days, weeks, or months, starting at a particular time
- Run and recur at weekly or monthly frequency but only on specific days, specific days of week, or specific days of month
- Run and recur at multiple times in a period – e.g., last Friday and Monday of every month, or at 5:15am and 5:15pm every day
Dates in Azure Scheduler jobs follow the ISO-8601 specification and include only the date.
Date-Time references in Azure Scheduler jobs follow the ISO-8601 specification and include both date and time parts. A Date-Time that does not specify a UTC offset is assumed to be UTC.
To create a simple schedule using the Azure Scheduler REST API, first register your subscription with a resource provider (the provider name for Scheduler is Microsoft.Scheduler), then create a job collection, and finally create a job. When you create a job, you can specify scheduling and recurrence using JSON like the one excerpted below:
{
"startTime": "2012-08-04T00:00Z", // optional
…
"recurrence": // optional
{
"frequency": "week", // can be "year" "month" "day" "week" "hour" "minute"
"interval": 1, // optional, how often to fire (default to 1)
"schedule": // optional (advanced scheduling specifics)
{
"weekDays": ["monday", "wednesday", "friday"],
"hours": [10, 22]
},
"count": 10, // optional (default to recur infinitely)
"endTime": "2012-11-04", // optional (default to recur infinitely)
},
…
}
The following table provides a high-level overview of the major elements related to recurrence and scheduling in a job:
| JSON name | Description |
|---|---|
| startTime | startTime is a Date-Time. For simple schedules, startTime is the first occurrence and for complex schedules, the job will start no sooner than startTime. |
| recurrence | The recurrence object specifies recurrence rules for the job and the recurrence the job will execute with. The recurrence object supports the elements frequency, interval, endTime, count, and schedule. If recurrence is defined, frequency is required; the other elements of recurrence are optional. |
| frequency | The frequency string representing the frequency unit at which the job recurs. Supported values are "minute", "hour", "day", "week", or "month." |
| interval | The interval is a positive integer and denotes the interval for the frequency that determines how often the job will run. For example, if interval is 3 and frequency is "week", the job recurs every 3 weeks. Azure Scheduler supports a maximum interval of 18 months for monthly frequency, 78 weeks for weekly frequency, or 548 days for daily frequency. For hour and minute frequency, the supported range is 1 <= interval <= 1000. |
| endTime | The endTime string specifies the date-time past which the job should not execute. It is not valid to have an endTime in the past. If no endTime or count is specified, the job runs infinitely. Both endTime and count cannot be included for the same job. |
| count | The count is a positive integer (greater than zero) that specifies the number of times this job should run before completing. The count represents the number of times the job runs before being determined as completed. For example, for a job that is executed daily with count 5 and start date of Monday, the job completes after execution on Friday. If the start date is in the past, the first execution is calculated from the creation time. If no endTime or count is specified, the job runs infinitely. Both endTime and count cannot be included for the same job. |
| schedule | A job with a specified frequency alters its recurrence based on a recurrence schedule. A schedule contains modifications based on minutes, hours, week days, month days, and week number. |
After this overview, let’s discuss each of these elements in detail.
| JSON name | Value type | Required? | Default value | Valid values | Example |
|---|---|---|---|---|---|
| startTime | String | No | None | ISO-8601 Date-Times | "startTime" : "2013-01-09T09:30:00-08:00" |
| recurrence | Object | No | None | Recurrence object | "recurrence" : { "frequency" : "monthly", "interval" : 1 } |
| frequency | String | Yes | None | "minute", "hour", "day", "week", "month" | "frequency" : "hour" |
| interval | Number | No | 1 | 1 to 1000. | "interval":10 |
| endTime | String | No | None | Date-Time value representing a time in the future | "endTime" : "2013-02-09T09:30:00-08:00" |
| count | Number | No | None | >= 1 | "count": 5 |
| schedule | Object | No | None | Schedule object | "schedule" : { "minute" : [30], "hour" : [8,17] } |
The following table captures how startTime controls how a job is run.
| startTime value | No recurrence | Recurrence. No schedule | Recurrence with schedule |
|---|---|---|---|
| No start time | Run once immediately | Run once immediately. Run subsequent executions based on calculating from last execution time | Run once immediately Run subsequent executions based on recurrence schedule |
| Start time in past | Run once immediately | Calculate first future execution time after start time, and run at that time Run subsequent executions based oncalculating from last execution time See example after this table for a further explanation |
Job starts no sooner than the specified start time. The first occurrence is based on the schedule calculated from the start time Run subsequent executions based on recurrence schedule |
| Start time in future or at present | Run once at specified start time | Run once at specified start time Run subsequent executions based on calculating from last execution time |
Job starts no sooner than the specified start time. The first occurrence is based on the schedule calculated from the start time Run subsequent executions based on recurrence schedule |
Let's see an example of what happens where startTime is in the past, with recurrence but no schedule. Assume that the current time is 2015-04-08 13:00, startTime is 2015-04-07 14:00, and recurrence is every 2 days (defined with frequency: day and interval: 2.) Note that the startTime is in the past, and occurs before the current time
Under these conditions, the first execution will be 2015-04-09 at 14:00. The Scheduler engine calculates execution occurrences from the start time. Any instances in the past are discarded. The engine uses the next instance that occurs in the future. So in this case, startTime is 2015-04-07 at 2:00pm, so the next instance is 2 days from that time, which is 2015-04-09 at 2:00pm.
Note that the first execution would be the same even if the startTime 2015-04-05 14:00 or 2015-04-01 14:00. After the first execution, subsequent executions are calculated using the scheduled – so they'd be at 2015-04-11 at 2:00pm, then 2015-04-13 at 2:00pm, then 2015-04-15 at 2:00pm, etc.
Finally, when a job has a schedule, if hours and/or minutes aren’t set in the schedule, they default to the hours and/or minutes of the first execution, respectively.
On one hand, a schedule can limit the number of job executions. For example, if a job with a "month" frequency has a schedule that runs on only day 31, the job runs in only those months that have a 31st day.
On the other hand, a schedule can also expand the number of job executions. For example, if a job with a "month" frequency has a schedule that runs on month days 1 and 2, the job runs on the 1st and 2nd days of the month instead of just once a month.
If multiple schedule elements are specified, the order of evaluation is from the largest to smallest – week number, month day, week day, hour, and minute.
The following table describes schedule elements in detail.
| JSON name | Description | Valid Values |
|---|---|---|
| minutes | Minutes of the hour at which the job will run |
|
| hours | Hours of the day at which the job will run |
|
| weekDays | Days of the week the job will run. Can only be specified with a weekly frequency. |
|
| monthlyOccurrences | Determines which days of the month the job will run. Can only be specified with a monthly frequency. |
{ "day": day,day is the day of the week the job will run, e.g. {Sunday} is every Sunday of the month. Required. Occurrence is occurrence of the day during the month, e.g. {Sunday, -1} is the last Sunday of the month. Optional. |
| monthDays | Day of the month the job will run. Can only be specified with a monthly frequency. |
|
The following are various examples of recurrence schedules – focusing on the schedule object and its sub-elements.
The schedules below all assume that the interval is set to 1. Also, one must assume the right frequency in accordance to what is in the schedule – e.g., one can't use frequency "day" and have a "monthDays" modification in the schedule. Such restrictions are described above.
| Example | Description |
|---|---|
{"hours":[5]} |
Run at 5AM Every Day. Azure Scheduler matches up each value in "hours" with each value in "minutes", one by one, to create a list of all the times at which the job is to be run. |
{"minutes":[15], "hours":[5]} |
Run at 5:15AM Every Day |
{"minutes":[15], "hours":[5,17]} |
Run at 5:15 AM and 5:15 PM Every Day |
{"minutes":[15,45], "hours":[5,17]} |
Run at 5:15AM, 5:45AM, 5:15PM, and 5:45PM Every Day |
{"minutes":[0,15,30,45]} |
Run Every 15 Minutes |
{hours":[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]} |
Run Every Hour. This job runs every hour. The minute is controlled by the startTime, if one is specified, or if none is specified, by the creation time. For example, if the start time or creation time (whichever applies) is 12:25 PM, the job will be run at 00:25, 01:25, 02:25, …, 23:25. The schedule is equivalent to having a job with frequency of "hour", an interval of 1, and no schedule. The difference is that this schedule could be used with different frequency and interval to create other jobs too. For example, if the frequency were "month", the schedule would run only once a month instead of every day if frequency were "day" |
{minutes:[0]} |
Run Every Hour on the Hour. This job also runs every hour, but on the hour (e.g. 12AM, 1AM, 2AM, etc.) This is equivalent to a job with frequency of "hour", a startTime with zero minutes, and no schedule if the frequency were "day", but if the frequency were "week" or "month," the schedule would execute only one day a week or one day a month, respectively. |
{"minutes":[15]} |
Run at 15 Minutes Past Hour Every Hour. Runs every hour, starting at 00:15AM, 1:15AM, 2:15AM, etc. and ending at 10:15PM and 11:15PM. |
{"hours":[17], "weekDays":["saturday"]} |
Run at 5PM on Saturdays Every Week |
{hours":[17], "weekDays":["monday", "wednesday", "friday"]} |
Run at 5PM on Monday, Wednesday, and Friday Every Week |
{"minutes":[15,45], "hours":[17], "weekDays":["monday", "wednesday", "friday"]} |
Run at 5:15PM and 5:45PM on Monday, Wednesday, and Friday Every Week |
{"hours":[5,17], "weekDays":["monday", "wednesday", "friday"]} |
Run at 5AM and 5PM on Monday, Wednesday, and Friday Every Week |
{"minutes":[15,45], "hours":[5,17], "weekDays":["monday", "wednesday", "friday"]} |
Run at 5:15AM, 5:45AM, 5:15PM, and 5:45PM on Monday, Wednesday, and Friday Every Week |
{"minutes":[0,15,30,45], "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} |
Run Every 15 Minutes on Weekdays |
{"minutes":[0,15,30,45], "hours": [9, 10, 11, 12, 13, 14, 15, 16] "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} |
Run Every 15 Minutes on Weekdays between 9AM and 4:45PM |
{"weekDays":["sunday"]} |
Run on Sundays at Start Time |
{"weekDays":["tuesday", "thursday"]} |
Run on Tuesdays and Thursdays at Start Time |
{"minutes":[0], "hours":[6], "monthDays":[28]} |
Run at 6AM on the 28th Day of Every Month (assuming frequency of month) |
{"minutes":[0], "hours":[6], "monthDays":[-1]} |
Run at 6AM on the Last Day of the Month. If you'd like to run a job on the last day of a month, use -1 instead of day 28, 29, 30, or 31. |
{"minutes":[0], "hours":[6], "monthDays":[1,-1]} |
Run at 6AM on the First and Last Day of Every Month |
{monthDays":[1,-1]} |
Run on the First and Last Day of Every Month at Start Time |
{monthDays":[1,14]} |
Run on the First and Fourteenth Day of Every Month at Start Time |
{monthDays":[2]} |
Run on the Second Day of the Month at Start Time |
{"minutes":[0], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1}]} |
Run on First Friday of Every Month at 5AM |
{"monthlyOccurrences":[{"day":"friday", "occurrence":1}]} |
: Run on First Friday of Every Month at Start Time |
{"monthlyOccurrences":[{"day":"friday", "occurrence":-3}]} |
Run on Third Friday from End of Month, Every Month, at Start Time |
{"minutes":[15], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} |
Run on First and Last Friday of Every Month at 5:15AM |
{"monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} |
Run on First and Last Friday of Every Month at Start Time |
{"monthlyOccurrences":[{"day":"friday", "occurrence":5}]} |
Run on Fifth Friday of Every Month at Start Time. If there is no fifth Friday in a month, this does not run, since it's scheduled to run on only fifth Fridays. You may consider using -1 instead of 5 for the occurrence if you want to run the job on the last occurring Friday of the month. |
{"minutes":[0,15,30,45], "monthlyOccurrences":[{"day":"friday", "occurrence":-1}]} |
Run Every 15 Minutes on Last Friday of the Month |
{"minutes":[15,45], "hours":[5,17], "monthlyOccurrences":[{"day":"wednesday", "occurrence":3}]} |
Run at 5:15AM, 5:45AM, 5:15PM, and 5:45PM on the 3rd Wednesday of Every Month |
Azure Scheduler concepts, terminology, and entity hierarchy
Get started using Scheduler in the Azure portal
Plans and billing in Azure Scheduler
Azure Scheduler REST API reference
Azure Scheduler PowerShell cmdlets reference
Azure Scheduler high-availability and reliability