Skip to content

Commit

Permalink
[How-tos] Remove step numbers in how-to docs (#2542)
Browse files Browse the repository at this point in the history 
* changes per Nick

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* updates per Mark

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* fix error

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

Co-authored-by: Mark Fussell <markfussell@gmail.com>
  • Loading branch information
@hhunter-ms @msfussell
hhunter-ms and msfussell committed Jun 20, 2022
1 parent 2cc9c74 commit 9e83de0
Show file tree
Hide file tree
Showing 6 changed files with 120 additions and 255 deletions.
70 changes: 19 additions & 51 deletions ...s/content/en/developing-applications/building-blocks/bindings/howto-bindings.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,31 +6,28 @@ description: "Invoke external systems with output bindings"
weight: 300
---

Output bindings enable you to invoke external resources without taking dependencies on special SDK or libraries.
For a complete sample showing output bindings, visit this [link](https://github.com/dapr/quickstarts/tree/master/tutorials/bindings).

## Example:

The below code example loosely describes an application that processes orders. In the example, there is an order processing service which has a Dapr sidecar. The order processing service uses Dapr to invoke external resources, in this case a Kafka, via an output binding.
With output bindings, you can invoke external resources without depending on special SDK or libraries. An output binding represents a resource that Dapr uses to invoke and send messages to. For a complete sample showing output bindings, [walk through the tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/bindings).

<img src="/images/building-block-output-binding-example.png" width=1000 alt="Diagram showing bindings of example service">

## 1. Create a binding
This guide uses a Kafka binding as an example. You can find your preferred binding spec from [the list of bindings components]({{< ref setup-bindings >}}).

An output binding represents a resource that Dapr uses to invoke and send messages to.

For the purpose of this guide, you'll use a Kafka binding. You can find a list of the different binding specs [here]({{< ref setup-bindings >}}).
## Create a binding

Create a new binding component with the name of `checkout`.

Inside the `metadata` section, configure Kafka related properties such as the topic to publish the message to and the broker.
Within the `metadata` section, configure Kafka-related properties, such as:

- The topic to which you'll publish the message
- The broker

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

{{< tabs "Self-Hosted (CLI)" Kubernetes >}}

{{% codetab %}}

Create the following YAML file, named `binding.yaml`, and save this to a `components` sub-folder in your application directory.
(Use the `--components-path` flag with `dapr run` to point to your custom components dir)
Use the `--components-path` flag with `dapr run` to point to your custom components directory.

```yaml
apiVersion: dapr.io/v1alpha1
Expand Down Expand Up @@ -60,8 +57,7 @@ spec:

{{% codetab %}}

To deploy this into a Kubernetes cluster, fill in the `metadata` connection details of your [desired binding component]({{< ref setup-bindings >}}) in the yaml below (in this case kafka), save as `binding.yaml`, and run `kubectl apply -f binding.yaml`.

To deploy the following `binding.yaml` file into a Kubernetes cluster, run `kubectl apply -f binding.yaml`.

```yaml
apiVersion: dapr.io/v1alpha1
Expand Down Expand Up @@ -91,7 +87,7 @@ spec:

{{< /tabs >}}

## 2. Send an event (Output binding)
## Send an event (output binding)

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

Expand Down Expand Up @@ -135,12 +131,6 @@ namespace EventService

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id orderprocessing --app-port 6001 --dapr-http-port 3601 --dapr-grpc-port 60001 --app-ssl dotnet run
```

{{% /codetab %}}

{{% codetab %}}
Expand Down Expand Up @@ -179,12 +169,6 @@ public class OrderProcessingServiceApplication {

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id orderprocessing --app-port 6001 --dapr-http-port 3601 --dapr-grpc-port 60001 mvn spring-boot:run
```

{{% /codetab %}}

{{% codetab %}}
Expand Down Expand Up @@ -213,12 +197,6 @@ while True:

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id orderprocessing --app-port 6001 --dapr-http-port 3601 --app-protocol grpc python3 OrderProcessingService.py
```

{{% /codetab %}}

{{% codetab %}}
Expand Down Expand Up @@ -257,12 +235,6 @@ func main() {

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id orderprocessing --app-port 6001 --dapr-http-port 3601 --dapr-grpc-port 60001 go run OrderProcessingService.go
```

{{% /codetab %}}

{{% codetab %}}
Expand Down Expand Up @@ -301,29 +273,25 @@ function sleep(ms) {
}
```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id orderprocessing --app-port 6001 --dapr-http-port 3601 --dapr-grpc-port 60001 npm start
```

{{% /codetab %}}

{{< /tabs >}}

All that's left now is to invoke the output bindings endpoint on a running Dapr instance.
Invoke the output bindings endpoint on a running Dapr instance.

You can also invoke the output bindings endpoint using HTTP:

```bash
curl -X POST -H 'Content-Type: application/json' http://localhost:3601/v1.0/bindings/checkout -d '{ "data": 100, "operation": "create" }'
```

As seen above, you invoked the `/binding` endpoint with the name of the binding to invoke, in our case its `checkout`.
The payload goes inside the mandatory `data` field, and can be any JSON serializable value.
As seen above:

1. The example invoked the `/binding` endpoint with `checkout`, the name of the binding to invoke.
1. The payload goes inside the mandatory `data` field, and can be any JSON serializable value.
1. The `operation` field tells the binding what action it needs to take. For example, [the Kafka binding supports the `create` operation]({{< ref "kafka.md#binding-support" >}}).

You'll also notice that there's an `operation` field that tells the binding what you need it to do.
You can check [here]({{< ref supported-bindings >}}) which operations are supported for every output binding.
You can check [which operations (specific to each component) are supported for every output binding]({{< ref supported-bindings >}}).

Watch this [video](https://www.youtube.com/watch?v=ysklxm81MTs&feature=youtu.be&t=1960) on how to use bi-directional output bindings.

Expand Down
69 changes: 17 additions & 52 deletions ...s/content/en/developing-applications/building-blocks/bindings/howto-triggers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,38 +8,33 @@ weight: 200

Using bindings, your code can be triggered with incoming events from different resources which can be anything: a queue, messaging pipeline, cloud-service, filesystem etc.

This is ideal for event-driven processing, data pipelines or just generally reacting to events and doing further processing.
This is ideal for event-driven processing, data pipelines, or generally reacting to events and performing further processing.

Dapr 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

For more info on bindings, read [this overview]({{<ref bindings-overview.md>}}).

## Example:

The below code example loosely describes an application that processes orders. In the example, there is an order processing service which has a Dapr sidecar. The checkout service uses Dapr to trigger the application via an input binding.
An input binding represents a resource that Dapr uses to read events from and push to your application. Read the [bindings overview for more information]({{<ref bindings-overview.md>}}).

<img src="/images/building-block-input-binding-example.png" width=1000 alt="Diagram showing bindings of example service">

## 1. Create a binding

An input binding represents a resource that Dapr uses to read events from and push to your application.
This guide uses a Kafka binding as an example. You can find your preferred binding spec from [the list of bindings components]({{< ref setup-bindings >}}).

For the purpose of this guide, you'll use a Kafka binding. You can find a list of supported binding components [here]({{< ref setup-bindings >}}).
## Create a binding

Create a new binding component with the name of `checkout`.

Inside the `metadata` section, configure Kafka related properties, such as the topic to publish the message to and the broker.
Inside the `metadata` section, configure Kafka-related properties, such as the topic to publish the message to and the broker.

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

{{< tabs "Self-Hosted (CLI)" Kubernetes >}}

{{% codetab %}}

Create the following YAML file, named `binding.yaml`, and save this to a `components` sub-folder in your application directory.
(Use the `--components-path` flag with `dapr run` to point to your custom components dir)
Use the `--components-path` flag with the `dapr run` command to point to your custom components directory.

```yaml
apiVersion: dapr.io/v1alpha1
Expand Down Expand Up @@ -69,8 +64,7 @@ spec:

{{% codetab %}}

To deploy this into a Kubernetes cluster, fill in the `metadata` connection details of your [desired binding component]({{< ref setup-bindings >}}) in the yaml below (in this case kafka), save as `binding.yaml`, and run `kubectl apply -f binding.yaml`.

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

```yaml
apiVersion: dapr.io/v1alpha1
Expand Down Expand Up @@ -100,13 +94,13 @@ spec:

{{< /tabs >}}

## 2. Listen for incoming events (input binding)
## Listen for incoming events (input binding)

Now configure your application to receive incoming events. If using HTTP, you need to listen on a `POST` endpoint with the name of the binding as specified in `metadata.name` in the file.
Configure your application to receive incoming events. If 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.

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

{{< tabs Dotnet Java Python Go JavaScript>}}
{{< tabs Dotnet Java Python Go Javascript>}}

{{% codetab %}}

Expand Down Expand Up @@ -134,12 +128,6 @@ namespace CheckoutService.controller

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id checkout --app-port 6002 --dapr-http-port 3602 --dapr-grpc-port 60002 --app-ssl dotnet run
```

{{% /codetab %}}

{{% codetab %}}
Expand All @@ -165,12 +153,6 @@ public class CheckoutServiceController {

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id checkout --app-port 6002 --dapr-http-port 3602 --dapr-grpc-port 60002 mvn spring-boot:run
```

{{% /codetab %}}

{{% codetab %}}
Expand All @@ -192,12 +174,6 @@ app.run(6002)

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id checkout --app-port 6002 --dapr-http-port 3602 --app-protocol grpc -- python3 CheckoutService.py
```

{{% /codetab %}}

{{% codetab %}}
Expand Down Expand Up @@ -232,12 +208,6 @@ func main() {

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id checkout --app-port 6002 --dapr-http-port 3602 --dapr-grpc-port 60002 go run CheckoutService.go
```

{{% /codetab %}}

{{% codetab %}}
Expand Down Expand Up @@ -265,28 +235,22 @@ async function start() {

```

Navigate to the directory containing the above code, then run the following command to launch a Dapr sidecar and run the application:

```bash
dapr run --app-id checkout --app-port 6002 --dapr-http-port 3602 --dapr-grpc-port 60002 dotnet npm start
```

{{% /codetab %}}

{{< /tabs >}}

### ACK-ing an event

In order to tell Dapr that you successfully processed an event in your application, return a `200 OK` response from your HTTP handler.
Tell Dapr you've successfully processed an event in your application by returning a `200 OK` response from your HTTP handler.

### Rejecting an event

In order to tell Dapr that the event was not processed correctly in your application and schedule it for redelivery, return any response other than `200 OK`. For example, a `500 Error`.
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`.

### Specifying 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:
You can override this by setting the following metadata property in `binding.yaml`:

```yaml
name: mybinding
Expand All @@ -298,11 +262,12 @@ spec:
```

### 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

* [Bindings building block]({{< ref bindings >}})
* [Bindings API]({{< ref bindings_api.md >}})
* [Components concept]({{< ref components-concept.md >}})
* [Supported bindings]({{< ref supported-bindings >}})
* [Supported bindings]({{< ref supported-bindings >}})
Loading

0 comments on commit 9e83de0

Please sign in to comment.