Dapr SDK for Go
This is the dapr SDK (client) for go (golang). It covers all of the APIs described in Dapr's protocol buffers with focus on developer productivity.
Installation
To install Dapr client package, you need to first install go and set up your development environment. To import Dapr go client in your code:
import "github.com/dapr/go-sdk/client"
Quick start
package main
import (
dapr "github.com/dapr/go-sdk/client"
)
func main() {
client, err := dapr.NewClient()
if err != nil {
panic(err)
}
defer client.Close()
//TODO: use the client here
}
Assuming you have Dapr CLI installed locally, you can then launch your app like this:
dapr run --app-id my-app --protocol grpc --app-port 50001 go run main.go
See example folder for complete example.
Examples
Few common Dapr client usage examples
State
For simple use-cases, Dapr client provides easy to use methods:
ctx := context.Background()
data := []byte("hello")
store := "my-store" // defined in the component YAML
// save state with the key
err = client.SaveStateData(ctx, store, "k1", "v1", data)
handleErrors(err)
// get state for key
out, etag, err := client.GetState(ctx, store, "k1")
handleErrors(err)
// delete state for key
err = client.DeleteState(ctx, store, "k1")
handleErrors(err)
The StateItem
type exposed by Dapr client provides more granular control options:
data := &client.StateItem{
Etag: "v1",
Key: "k1",
Metadata: map[string]string{
"key1": "value1",
"key2": "value2",
},
Value: []byte("hello"),
Options: &client.StateOptions{
Concurrency: client.StateConcurrencyLastWrite,
Consistency: client.StateConsistencyStrong,
RetryPolicy: &client.StateRetryPolicy{
Threshold: 3,
Pattern: client.RetryPatternExponential,
Interval: time.Duration(5 * time.Second),
},
},
}
err = client.SaveStateItem(ctx, store, data)
Similar StateOptions
exist on GetDate
and DeleteState
methods. Additionally, Dapr client also provides a method to save multiple state items at once:
data := &client.State{
StoreName: "my-store",
States: []*client.StateItem{
{
Key: "k1",
Value: []byte("message 1"),
},
{
Key: "k2",
Value: []byte("message 2"),
},
},
}
err = client.SaveState(ctx, data)
PubSub
To publish data onto a topic the Dapr client provides a simple method:
data := []byte("hello")
err = client.PublishEvent(ctx, "topic-name", data)
handleErrors(err)
Service Invocation
To invoke a specific method on another service running with Dapr sidecar, the Dapr client provides two options. To invoke a service without any data:
resp, err = client.InvokeService(ctx, "service-name", "method-name")
handleErrors(err)
And to invoke a service with data:
data := []byte("hello")
resp, err := client.InvokeServiceWithContent(ctx, "service-name", "method-name", "text/plain", data)
handleErrors(err)
Bindings
Similarly to Service, Dapr client provides two methods to invoke an operation on a Dapr-defined binding. Dapr supports input, output, and bidirectional bindings so the first methods supports all of them along with metadata options:
data := []byte("hello")
opt := map[string]string{
"opt1": "value1",
"opt2": "value2",
}
resp, meta, err := client.InvokeBinding(ctx, "binding-name", "operation-name", data, opt)
handleErrors(err)
And for simple, output only biding:
data := []byte("hello")
err = client.InvokeOutputBinding(ctx, "binding-name", "operation-name", data)
handleErrors(err)
Secrets
The Dapr client also provides access to the runtime secrets that can be backed by any number of secrete stores (e.g. Kubernetes Secrets, Hashicorp Vault, or Azure KeyVault):
opt := map[string]string{
"version": "2",
}
secret, err = client.GetSecret(ctx, "store-name", "secret-name", opt)
handleErrors(err)
Contributing to Dapr go client
See the Contribution Guide to get started with building and developing.