dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Apply suggestions from code review 

Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
This commit is contained in:
Whit Waldo 2025-01-22 21:04:43 -06:00 committed by GitHub
parent f4683139b6
commit 2ec32b6213
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 40 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md
View File

@ -14,7 +14,7 @@ which are common across all supported languages.
### Job identity ## Job identity
All jobs are registered with a case-sensitive job name. These names are intended to be unique across all services All jobs are registered with a case-sensitive job name. These names are intended to be unique across all services
interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as
@ -23,44 +23,43 @@ to indicate which job a triggered invocation is associated with.
Only one job can be associated with a name at any given time. Any attempt to create a new job using the same name Only one job can be associated with a name at any given time. Any attempt to create a new job using the same name
as an existing job will result in an overwrite of this existing job. as an existing job will result in an overwrite of this existing job.
### Scheduling Jobs ## Scheduling Jobs
A job can be scheduled using any of the following mechanisms: A job can be scheduled using any of the following mechanisms:
- Intervals using Cron expressions, duration values or period expressions - Intervals using Cron expressions, duration values, or period expressions
- Specific dates and times - Specific dates and times
Note that for all time-based schedules, if a timestamp is provided with a timezone via the RFC3339 specification, that For all time-based schedules, if a timestamp is provided with a time zone via the RFC3339 specification, that
timezone will be used instead, but when not provided, the time will be assumed to be the timezone used by the server time zone is used. When not provided, the time zone used by the server running Dapr is used.
running Dapr. In other words, do **not** assume that times will run in UTC unless you've specified this when scheduling In other words, do **not** assume that times run in UTC time zone, unless otherwise specified when scheduling
the job. the job.
#### Schedule using a Cron expression ### Schedule using a Cron expression
When using a Cron expression to schedule a job to execute on a specific interval, the expression is written using 6 When scheduling a job to execute on a specific interval using a Cron expression, the expression is written using 6
fields spanning the values specified in the table below: fields spanning the values specified in the table below:
| seconds | minutes | hours | day of month | month | day of week | | seconds | minutes | hours | day of month | month | day of week |
| -- | -- | -- | -- | -- | -- | | -- | -- | -- | -- | -- | -- |
| 0-59 | 0-59 | 0-23 | 1-31 | 1-12/jan-dec | 0-6/sun-sat | | 0-59 | 0-59 | 0-23 | 1-31 | 1-12/jan-dec | 0-6/sun-sat |
##### Example 1 #### Example 1
"0 30 * * * *" will trigger every hour on the half-hour mark `"0 30 * * * *"` triggers every hour on the half-hour mark.
##### Example 2 #### Example 2
"0 15 3 * * *" will trigger every day at 03:15 `"0 15 3 * * *"` triggers every day at 03:15.
#### Schedule using a duration value ### Schedule using a duration value
This reflects use of a Go duration string documented [here](https://pkg.go.dev/time#ParseDuration) in which You can schedule jobs using [a Go duration string](https://pkg.go.dev/time#ParseDuration), in which
a string consists of a possibly signed sequence of decimal numbers, each with an optional fraction and a unit suffix. a string consists of a (possibly) signed sequence of decimal numbers, each with an optional fraction and a unit suffix.
Valid time units are "ns", "us", "ms", "s", "m" or "h". Valid time units are `"ns"`, `"us"`, `"ms"`, `"s"`, `"m"`, or `"h"`.
##### Example 1 #### Example 1
"2h45m" will trigger every two hours and 45 minutes `"2h45m"` triggers every 2 hours and 45 minutes.
##### Example 2 #### Example 2
"37m25s" will trigger every 37 minutes and 25 seconds `"37m25s"` triggers every 37 minutes and 25 seconds.
#### Schedule using a period expression ### Schedule using a period expression
The following period expressions are supported. Note that the "@every" expression also accepts a Go duration string The following period expressions are supported. The "@every" expression also accepts a [Go duration string](https://pkg.go.dev/time#ParseDuration).
as documented above:
| Entry | Description | Equivalent Cron expression | | Entry | Description | Equivalent Cron expression |
| -- | -- | -- | | -- | -- | -- |
@ -71,22 +70,22 @@ as documented above:
| @daily or @midnight | Run once a day at midnight | 0 0 0 * * * | | @daily or @midnight | Run once a day at midnight | 0 0 0 * * * |
| @hourly | Run once an hour at the beginning of the hour | 0 0 * * * * | | @hourly | Run once an hour at the beginning of the hour | 0 0 * * * * |
#### Schedule using a specific date/time ### Schedule using a specific date/time
A Job can also be scheduled to run at a particular point in time by providing a date that's specified using the A job can also be scheduled to run at a particular point in time by providing a date using the
[RFC3339 specification](https://www.rfc-editor.org/rfc/rfc3339). [RFC3339 specification](https://www.rfc-editor.org/rfc/rfc3339).
##### Example 1 #### Example 1
"2025-12-09T16:09:53+00:00" Indicates that the job should be run on December 9, 2025 at 4:09:53 PM UTC. `"2025-12-09T16:09:53+00:00"` Indicates that the job should be run on December 9, 2025 at 4:09:53 PM UTC.
### Scheduled triggers ## Scheduled triggers
When a scheduled Dapr Job is triggered, the runtime sends a message back to the service that scheduled the job using When a scheduled Dapr job is triggered, the runtime sends a message back to the service that scheduled the job using
either the HTTP or gRPC approach, depending on which is registered with Dapr when the service starts. either the HTTP or gRPC approach, depending on which is registered with Dapr when the service starts.
#### gRPC ### gRPC
When a job reaches its scheduled trigger time, the triggered job is sent back to the application via the following When a job reaches its scheduled trigger time, the triggered job is sent back to the application via the following
callback function: callback function:
*Note: The following example is in Go but applies to any programming language with gRPC support.* > **Note:** The following example is in Go, but applies to any programming language with gRPC support.
```go ```go
import rtv1 "github.com/dapr/dapr/pkg/proto/runtime/v1" import rtv1 "github.com/dapr/dapr/pkg/proto/runtime/v1"
@ -97,7 +96,7 @@ func (s *JobService) OnJobEventAlpha1(ctx context.Context, in *rtv1.JobEventRequ
``` ```
This function processes the triggered jobs within the context of your gRPC server. When you set up the server, ensure that This function processes the triggered jobs within the context of your gRPC server. When you set up the server, ensure that
you register the callback server, which will invoke this function when a job is triggered: you register the callback server, which invokes this function when a job is triggered:
```go ```go
... ...
@ -108,16 +107,16 @@ rtv1.RegisterAppCallbackAlphaServer(server, js)
In this setup, you have full control over how triggered jobs are received and processed, as they are routed directly In this setup, you have full control over how triggered jobs are received and processed, as they are routed directly
through this gRPC method. through this gRPC method.
#### HTTP ### HTTP
If a gRPC server isn't registered with Dapr when the application starts up, Dapr will instead trigger jobs by making a If a gRPC server isn't registered with Dapr when the application starts up, Dapr instead triggers jobs by making a
POST request to the endpoint `/job/<job-name>`. The body will include the following information about the job: POST request to the endpoint `/job/<job-name>`. The body includes the following information about the job:
- Schedule: When the job triggers occur - `Schedule`: When the job triggers occur
- RepeatCount: An optional value indicating how often the job should repeat - `RepeatCount`: An optional value indicating how often the job should repeat
- DueTime: An optional point in time representing either the one time when the job should execute (if not recurring) - DueTime: An optional point in time representing either the one time when the job should execute (if not recurring)
or the start join from which the schedule should take effect or the start join from which the schedule should take effect
- Ttl: An optional value indicating when the job should expire - `Ttl`: An optional value indicating when the job should expire
- Payload: A collection of bytes containing data originally stored when the job was scheduled - `Payload`: A collection of bytes containing data originally stored when the job was scheduled
The DueTime and Ttl fields will reflect an RC3339 timestamp value reflective of the timezone provided when the job was The `DueTime` and `Ttl` fields will reflect an RC3339 timestamp value reflective of the time zone provided when the job was
originally scheduled. If no timezone was provided, these values will indicate the timezone used by the server running originally scheduled. If no time zone was provided, these values indicate the time zone used by the server running
Dapr. Dapr.