From b4e6d4a09e10a03564c87b591883fb8bfc6af0cc Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Wed, 22 Jan 2025 07:43:08 -0600 Subject: [PATCH] Reorganized technical details of Jobs implementation out from the How To page and into a separate one Signed-off-by: Whit Waldo --- ...owto-schedule-and-handle-triggered-jobs.md | 64 +-------- .../jobs/jobs-features-concepts.md | 123 ++++++++++++++++++ 2 files changed, 126 insertions(+), 61 deletions(-) create mode 100644 daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md index 0a5dba3b1..4ee8f2205 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md @@ -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/`. 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/", 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 ... diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md new file mode 100644 index 000000000..52eff75f7 --- /dev/null +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md @@ -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/`. 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. \ No newline at end of file