Bindings API reference

Dapr provides bi-directional binding capabilities for applications and a consistent approach to interacting with different cloud/on-premise services or systems. Developers can invoke output bindings using the Dapr API, and have the Dapr runtime trigger an application with input bindings.

Examples for bindings include , Rabbit MQ, Azure Event Hubs, AWS SQS, GCP Storage to name a few.

A Dapr Binding yaml file has the following structure:

The metadata.name is the name of the binding.

If running self hosted locally, place this file in your components folder next to your state store and message queue yml configurations.

If running on kubernetes apply the component to your cluster.

On startup Dapr sends a OPTIONS request to the metadata.name endpoint and expects a different status code as NOT FOUND (404) if this application wants to subscribe to the binding.

The metadata section is an open key/value metadata pair that allows a binding to define connection properties, as well as custom properties unique to the component implementation.

For example, here’s how a Python application subscribes for events from Kafka using a Dapr API compliant platform. Note how the metadata.name value kafkaevent in the components matches the POST route name in the Python code.

Kafka Component

apiVersion: dapr.io/v1alpha1
kind: Component
  name: kafkaevent
  namespace: default
spec:
  type: bindings.kafka
  version: v1
  metadata:
    value: "http://localhost:5050"
  - name: topics
    value: "someTopic"
  - name: publishTopic
    value: "someTopic2"
  - name: consumerGroup
    value: "group1"

Python Code

from flask import Flask
app = Flask(__name__)
@app.route("/kafkaevent", methods=['POST'])
def incoming():
    print("Hello from Kafka!", flush=True)
    return "Kafka Event Processed!"

Binding endpoints

Bindings are discovered from component yaml files. Dapr calls this endpoint on startup to ensure that app can handle this call. If the app doesn’t have the endpoint, Dapr ignores it.

HTTP Request

HTTP Response codes

URL Parameters

Note, all URL parameters are case-sensitive.

Binding payload

In order to deliver binding inputs, a POST call is made to user code with the name of the binding as the URL path.

HTTP Request

POST http://localhost:<appPort>/<name>

HTTP Response codes

URL Parameters

HTTP Response body (optional)

Example: Dapr stores stateDataToStore into a state store named “stateStore”. Dapr sends jsonObject to the output bindings named “storage” and “queue” in parallel. If concurrency is not set, it is sent out sequential (the example below shows these operations are done in parallel)

    "storeName": "stateStore",
    "state": stateDataToStore,
    "concurrency": "parallel",
    "data": jsonObject,
}

This endpoint lets you invoke a Dapr output binding. Dapr bindings support various operations, such as create.

See the on each binding to see the list of supported operations.

HTTP Response codes

Payload

The bindings endpoint receives the following JSON payload:

{
  "data": "",
  "metadata": {
    "": ""
  },
  "operation": ""
}

Note, all URL parameters are case-sensitive.

The data field takes any JSON serializable value and acts as the payload to be sent to the output binding. The metadata field is an array of key/value pairs and allows you to set binding specific metadata for each call. The operation field tells the Dapr binding which operation it should perform.

Examples

curl -X POST http://localhost:3500/v1.0/bindings/myKafka \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "key": "redis-key-1"
        },
      }'

Common metadata values

Last modified November 12, 2021 : Merge pull request #1949 from willtsai/az-staticwebapp-versioning (c40e456)