How-To: Trigger your application with input bindings

Use Dapr input bindings to trigger event driven applications

With input bindings, you can trigger your application when an event from an external resource occurs. An external resource could be a queue, messaging pipeline, cloud-service, filesystem, etc. An optional payload and metadata may be sent with the request.

Input bindings are ideal for event-driven processing, data pipelines, or generally reacting to events and performing further processing. Dapr input bindings allow you to:

  • Receive events without including specific SDKs or libraries
  • Replace bindings without changing your code
  • Focus on business logic and not the event resource implementation

Diagram showing bindings of example service

This guide uses a Kafka binding as an example. You can find your preferred binding spec from the list of bindings components. In this guide:

  1. The example invokes the /binding endpoint with checkout, the name of the binding to invoke.
  2. The payload goes inside the mandatory data field, and can be any JSON serializable value.
  3. The operation field tells the binding what action it needs to take. For example, the Kafka binding supports the create operation.

Note

If you haven’t already, try out the bindings quickstart for a quick walk-through on how to use the bindings API.

Create a binding

Create a binding.yaml file and save to a components sub-folder in your application directory.

Create a new binding component named checkout. Within the metadata section, configure the following Kafka-related properties:

  • The topic to which you’ll publish the message
  • The broker

When creating the binding component, specify the supported direction of the binding.

Use the --resources-path flag with the dapr run command to point to your custom resources directory.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: checkout
  5. spec:
  6. type: bindings.kafka
  7. version: v1
  8. metadata:
  9. # Kafka broker connection setting
  10. - name: brokers
  11. value: localhost:9092
  12. # consumer configuration: topic and consumer group
  13. - name: topics
  14. value: sample
  15. - name: consumerGroup
  16. value: group1
  17. # publisher configuration: topic
  18. - name: publishTopic
  19. value: sample
  20. - name: authRequired
  21. value: false
  22. - name: direction
  23. value: input

To deploy into a Kubernetes cluster, run kubectl apply -f binding.yaml.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: checkout
  5. spec:
  6. type: bindings.kafka
  7. version: v1
  8. metadata:
  9. # Kafka broker connection setting
  10. - name: brokers
  11. value: localhost:9092
  12. # consumer configuration: topic and consumer group
  13. - name: topics
  14. value: sample
  15. - name: consumerGroup
  16. value: group1
  17. # publisher configuration: topic
  18. - name: publishTopic
  19. value: sample
  20. - name: authRequired
  21. value: false
  22. - name: direction
  23. value: input

Listen for incoming events (input binding)

Configure your application to receive incoming events. If you’re using HTTP, you need to:

  • Listen on a POST endpoint with the name of the binding, as specified in metadata.name in the binding.yaml file.
  • Verify your application allows Dapr to make an OPTIONS request for this endpoint.

Below are code examples that leverage Dapr SDKs to demonstrate an output binding.

  1. //dependencies
  2. using System.Collections.Generic;
  3. using System.Threading.Tasks;
  4. using System;
  5. using Microsoft.AspNetCore.Mvc;
  6. //code
  7. namespace CheckoutService.controller
  8. {
  9. [ApiController]
  10. public class CheckoutServiceController : Controller
  11. {
  12. [HttpPost("/checkout")]
  13. public ActionResult<string> getCheckout([FromBody] int orderId)
  14. {
  15. Console.WriteLine("Received Message: " + orderId);
  16. return "CID" + orderId;
  17. }
  18. }
  19. }
  1. //dependencies
  2. import org.springframework.web.bind.annotation.*;
  3. import org.slf4j.Logger;
  4. import org.slf4j.LoggerFactory;
  5. import reactor.core.publisher.Mono;
  6. //code
  7. @RestController
  8. @RequestMapping("/")
  9. public class CheckoutServiceController {
  10. private static final Logger log = LoggerFactory.getLogger(CheckoutServiceController.class);
  11. @PostMapping(path = "/checkout")
  12. public Mono<String> getCheckout(@RequestBody(required = false) byte[] body) {
  13. return Mono.fromRunnable(() ->
  14. log.info("Received Message: " + new String(body)));
  15. }
  16. }
  1. #dependencies
  2. import logging
  3. from dapr.ext.grpc import App, BindingRequest
  4. #code
  5. app = App()
  6. @app.binding('checkout')
  7. def getCheckout(request: BindingRequest):
  8. logging.basicConfig(level = logging.INFO)
  9. logging.info('Received Message : ' + request.text())
  10. app.run(6002)
  1. //dependencies
  2. import (
  3. "encoding/json"
  4. "log"
  5. "net/http"
  6. "github.com/gorilla/mux"
  7. )
  8. //code
  9. func getCheckout(w http.ResponseWriter, r *http.Request) {
  10. w.Header().Set("Content-Type", "application/json")
  11. var orderId int
  12. err := json.NewDecoder(r.Body).Decode(&orderId)
  13. log.Println("Received Message: ", orderId)
  14. if err != nil {
  15. log.Printf("error parsing checkout input binding payload: %s", err)
  16. w.WriteHeader(http.StatusOK)
  17. return
  18. }
  19. }
  20. func main() {
  21. r := mux.NewRouter()
  22. r.HandleFunc("/checkout", getCheckout).Methods("POST", "OPTIONS")
  23. http.ListenAndServe(":6002", r)
  24. }
  1. //dependencies
  2. import { DaprServer, CommunicationProtocolEnum } from '@dapr/dapr';
  3. //code
  4. const daprHost = "127.0.0.1";
  5. const serverHost = "127.0.0.1";
  6. const serverPort = "6002";
  7. const daprPort = "3602";
  8. start().catch((e) => {
  9. console.error(e);
  10. process.exit(1);
  11. });
  12. async function start() {
  13. const server = new DaprServer({
  14. serverHost,
  15. serverPort,
  16. communicationProtocol: CommunicationProtocolEnum.HTTP,
  17. clientOptions: {
  18. daprHost,
  19. daprPort,
  20. }
  21. });
  22. await server.binding.receive('checkout', async (orderId) => console.log(`Received Message: ${JSON.stringify(orderId)}`));
  23. await server.startServer();
  24. }

ACK an event

Tell Dapr you’ve successfully processed an event in your application by returning a 200 OK response from your HTTP handler.

Reject an event

Tell Dapr the event was not processed correctly in your application and schedule it for redelivery by returning any response other than 200 OK. For example, a 500 Error.

Specify a custom route

By default, incoming events will be sent to an HTTP endpoint that corresponds to the name of the input binding. You can override this by setting the following metadata property in binding.yaml:

  1. name: mybinding
  2. spec:
  3. type: binding.rabbitmq
  4. metadata:
  5. - name: route
  6. value: /onevent

Event delivery Guarantees

Event delivery guarantees are controlled by the binding implementation. Depending on the binding implementation, the event delivery can be exactly once or at least once.

References

Last modified October 12, 2023: Update config.toml (#3826) (0ffc2e7)