mirror of https://github.com/dapr/docs.git
Reorganized technical details of Jobs implementation out from the How To page and into a separate one
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
This commit is contained in:
Whit Waldo
parent
9fdc8bd843
commit
b4e6d4a09e
|
|
@ -2,7 +2,7 @@
|
|||
type: docs
|
||||
title: "How-To: Schedule and handle triggered jobs"
|
||||
linkTitle: "How-To: Schedule and handle triggered jobs"
|
||||
weight: 2000
|
||||
weight: 5000
|
||||
description: "Learn how to use the jobs API to schedule and handle triggered jobs"
|
||||
---
|
||||
|
||||
|
|
@ -92,66 +92,8 @@ In this example, at trigger time, which is `@every 1s` according to the `Schedul
|
|||
}
|
||||
```
|
||||
|
||||
At the trigger time, the `prodDBBackupHandler` function is called, executing the desired business logic for this job at trigger time. For example:
|
||||
|
||||
#### HTTP
|
||||
|
||||
When you create a job using Dapr's Jobs API, Dapr will automatically assume there is an endpoint available at
|
||||
`/job/<job-name>`. For instance, if you schedule a job named `test`, Dapr expects your application to listen for job
|
||||
events at `/job/test`. Ensure your application has a handler set up for this endpoint to process the job when it is
|
||||
triggered. For example:
|
||||
|
||||
*Note: The following example is in Go but applies to any programming language.*
|
||||
|
||||
```go
|
||||
|
||||
func main() {
|
||||
...
|
||||
http.HandleFunc("/job/", handleJob)
|
||||
http.HandleFunc("/job/<job-name>", specificJob)
|
||||
...
|
||||
}
|
||||
|
||||
func specificJob(w http.ResponseWriter, r *http.Request) {
|
||||
// Handle specific triggered job
|
||||
}
|
||||
|
||||
func handleJob(w http.ResponseWriter, r *http.Request) {
|
||||
// Handle the triggered jobs
|
||||
}
|
||||
```
|
||||
|
||||
#### gRPC
|
||||
|
||||
When a job reaches its scheduled trigger time, the triggered job is sent back to the application via the following
|
||||
callback function:
|
||||
|
||||
*Note: The following example is in Go but applies to any programming language with gRPC support.*
|
||||
|
||||
```go
|
||||
import rtv1 "github.com/dapr/dapr/pkg/proto/runtime/v1"
|
||||
...
|
||||
func (s *JobService) OnJobEventAlpha1(ctx context.Context, in *rtv1.JobEventRequest) (*rtv1.JobEventResponse, error) {
|
||||
// Handle the triggered job
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```go
|
||||
...
|
||||
js := &JobService{}
|
||||
rtv1.RegisterAppCallbackAlphaServer(server, js)
|
||||
```
|
||||
|
||||
In this setup, you have full control over how triggered jobs are received and processed, as they are routed directly
|
||||
through this gRPC method.
|
||||
|
||||
#### SDKs
|
||||
|
||||
For SDK users, handling triggered jobs is simpler. When a job is triggered, Dapr will automatically route the job to the
|
||||
event handler you set up during the server initialization. For example, in Go, you'd register the event handler like this:
|
||||
When a job is triggered, Dapr will automatically route the job to the event handler you set up during the server
|
||||
initialization. For example, in Go, you'd register the event handler like this:
|
||||
|
||||
```go
|
||||
...
|
||||
|
|
|
|||
|
|
@ -0,0 +1,123 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Features and concepts"
|
||||
linkTitle: "Features and concepts"
|
||||
weight: 2000
|
||||
description: "Learn more about the Dapr Jobs features and concepts"
|
||||
---
|
||||
|
||||
Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive
|
||||
into the features and concepts included with the Dapr Jobs engine and SDKs. Dapr Jobs exposes several core capabilities
|
||||
which are common across all supported languages.
|
||||
|
||||
## Jobs
|
||||
|
||||
Dapr Jobs provide a robust and highly-scalable API for scheduling operations to be triggered in the future.
|
||||
|
||||
### Job identity
|
||||
|
||||
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
|
||||
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
|
||||
as an existing job will result in an overwrite of this existing job.
|
||||
|
||||
### Scheduling Jobs
|
||||
A job can be scheduled using any of the following mechanisms:
|
||||
- Intervals using Cron expressions, duration values or period expressions
|
||||
- Specific dates and times
|
||||
|
||||
Note that for all time-based schedules, if a timestamp is provided with a timezone 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
|
||||
running Dapr. In other words, do **not** assume that times will run in UTC unless you've specified this when scheduling
|
||||
the job.
|
||||
|
||||
#### 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
|
||||
fields spanning the values specified in the table below:
|
||||
|
||||
| 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 |
|
||||
|
||||
##### Example 1
|
||||
"0 30 * * * *" will trigger every hour on the half-hour mark
|
||||
|
||||
##### Example 2
|
||||
"0 15 3 * * *" will trigger every day at 03:15
|
||||
|
||||
#### Schedule using a duration value
|
||||
This reflects use of a Go duration string documented [here](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.
|
||||
Valid time units are "ns", "us", "ms", "s", "m" or "h".
|
||||
|
||||
##### Example 1
|
||||
"2h45m" will trigger every two hours and 45 minutes
|
||||
|
||||
##### Example 2
|
||||
"37m25s" will trigger every 37 minutes and 25 seconds
|
||||
|
||||
#### Schedule using a period expression
|
||||
The following period expressions are supported. Note that the "@every" expression also accepts a Go duration string
|
||||
as documented above:
|
||||
|
||||
| Entry | Description | Equivalent Cron expression |
|
||||
| -- | -- | -- |
|
||||
| @every | Run every (e.g. "@every 1h30m") | N/A |
|
||||
| @yearly (or @annually) | Run once a year, midnight, January 1st | 0 0 0 1 1 * |
|
||||
| @monthly | Run once a month, midnight, first of month | 0 0 0 1 * * |
|
||||
| @weekly | Run once a week, midnight on Sunday | 0 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 * * * * |
|
||||
|
||||
#### 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
|
||||
[RFC3339 specification](https://www.rfc-editor.org/rfc/rfc3339).
|
||||
|
||||
##### 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.
|
||||
|
||||
### Scheduled triggers
|
||||
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.
|
||||
|
||||
#### gRPC
|
||||
When a job reaches its scheduled trigger time, the triggered job is sent back to the application via the following
|
||||
callback function:
|
||||
|
||||
*Note: The following example is in Go but applies to any programming language with gRPC support.*
|
||||
|
||||
```go
|
||||
import rtv1 "github.com/dapr/dapr/pkg/proto/runtime/v1"
|
||||
...
|
||||
func (s *JobService) OnJobEventAlpha1(ctx context.Context, in *rtv1.JobEventRequest) (*rtv1.JobEventResponse, error) {
|
||||
// Handle the triggered job
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```go
|
||||
...
|
||||
js := &JobService{}
|
||||
rtv1.RegisterAppCallbackAlphaServer(server, js)
|
||||
```
|
||||
|
||||
In this setup, you have full control over how triggered jobs are received and processed, as they are routed directly
|
||||
through this gRPC method.
|
||||
|
||||
#### HTTP
|
||||
If a gRPC server isn't registered with Dapr when the application starts up, Dapr will instead trigger jobs by making a
|
||||
POST request to the endpoint `/job/<job-name>`. The body will include the following information about the job:
|
||||
- Schedule: When the job triggers occur
|
||||
- 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)
|
||||
or the start join from which the schedule should take effect
|
||||
- Ttl: An optional value indicating when the job should expire
|
||||
- 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
|
||||
originally scheduled. If no timezone was provided, these values will indicate the timezone used by the server running
|
||||
Dapr.
|
||||
Loading…
Reference in New Issue