dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docs/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md

6.5 KiB
Raw Blame History

type title linkTitle weight description
docs Publishing & subscribing messages with Cloudevents Messages with Cloudevents 2100 Learn why Dapr uses CloudEvents, how they work in Dapr pub/sub, and how to create CloudEvents.

To enable message routing and provide additional context with each message, Dapr uses the CloudEvents 1.0 specification as its message format. Any message sent by an application to a topic using Dapr is automatically wrapped in a CloudEvents envelope, using the [Content-Type header value]({{< ref "pubsub-overview.md#content-types" >}}) for datacontenttype attribute.

Dapr uses CloudEvents to provide additional context to the event payload, enabling features like:

  • Tracing
  • Content-type for proper deserialization of event data
  • Verification of sender application

CloudEvents example

A publish operation to Dapr results in a cloud event envelope containing the following fields:

  • id
  • source
  • specversion
  • type
  • traceparent
  • traceid
  • tracestate
  • topic
  • pubsubname
  • time
  • datacontenttype (optional)

The following example demonstrates a cloud event generated by Dapr for a publish operation to the orders topic that includes a W3C traceid unique to the message, the data and the fields for the CloudEvent where the data content is serialized as JSON.

{
  "topic": "orders",
  "pubsubname": "order_pub_sub",
  "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
  "tracestate": "",
  "data": {
    "orderId": 1
  },
  "id": "5929aaac-a5e2-4ca1-859c-edfe73f11565",
  "specversion": "1.0",
  "datacontenttype": "application/json; charset=utf-8",
  "source": "checkout",
  "type": "com.dapr.event.sent",
  "time": "2020-09-23T06:23:21Z",
  "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01"
}

As another example of a v1.0 CloudEvent, the following shows data as XML content in a CloudEvent message serialized as JSON:

{
    "specversion" : "1.0",
    "type" : "xml.message",
    "source" : "https://example.com/message",
    "subject" : "Test XML Message",
    "id" : "id-1234-5678-9101",
    "time" : "2020-09-23T06:23:21Z",
    "datacontenttype" : "text/xml",
    "data" : "<note><to>User1</to><from>user2</from><message>hi</message></note>"
}

{{% alert title="Important" color="warning" %}} While you can specify traceid/traceparent and tracestate in the metadata request, it's recommended to use Open Telementry and Zipkin protocols for distributed traces. [Learn more about distributed tracing.]({{< ref "tracing-overview.md" >}})

{{% /alert %}}

Override CloudEvent values

When not provided, Dapr automatically generates several CloudEvent properties. You can override these generated CloudEvent properties by providing the following optional metadata keys:

  • cloudevent-id: overrides id
  • cloudevent-source: overrides source
  • cloudevent-type: overrides type
  • cloudevent-traceid: overrides traceid
  • cloudevent-tracestate: overrides tracestate
  • cloudevent-traceparent: overrides traceparent

The CloudEvent override metadata properties apply globally for all pub/sub components.

For example, to override the applicable values from [the first CloudEvent example above]({{< ref "#cloudevents-example" >}}):

{
  "topic": "orders",
  "pubsubname": "order_pub_sub",
  "specversion": "1.0",
  "datacontenttype": "application/json; charset=utf-8",
  "cloudevent-source": "checkout",
  "cloudevent-type": "com.dapr.event.sent",
  "time": "2020-09-23T06:23:21Z",
}

{{% alert title="Important" color="warning" %}} While you can specify and then override traceid/traceparent and tracestate, doing this may interfere with tracing tools. It's recommended to use Open Telementry and Zipkin protocols for distributed traces. [Learn more about distributed tracing.]({{< ref tracing-overview.md >}})

{{% /alert %}}

Publish your own CloudEvent

If you want to use your own CloudEvent, make sure to specify the [datacontenttype]({{< ref "pubsub-overview.md#setting-message-content-types" >}}) as application/cloudevents+json. If the CloudEvent that was authored by the app does not contain the minimum required fields in the CloudEvent specification, the message is rejected. Dapr adds the following fields to the CloudEvent if they are missing:

  • time
  • traceid
  • traceparent
  • tracestate
  • topic
  • pubsubname
  • source
  • type
  • specversion

You can add additional fields to a custom CloudEvent that are not part of the official CloudEvent specification. Dapr will pass these fields as-is.

Example

{{< tabs "Dapr CLI" "HTTP API (Bash)" "HTTP API (PowerShell)">}}

{{% codetab %}}

Publish a CloudEvent to the orders topic:

dapr publish --publish-app-id orderprocessing --pubsub order-pub-sub --topic orders --data '{\"orderId\": \"100\"}'

{{% /codetab %}}

{{% codetab %}}

Publish a CloudEvent to the orders topic:

curl -X POST http://localhost:3601/v1.0/publish/order-pub-sub/orders -H "Content-Type: application/cloudevents+json" -d '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"orderId": "100"}}'

{{% /codetab %}}

{{% codetab %}}

Publish a CloudEvent to the orders topic:

Invoke-RestMethod -Method Post -ContentType 'application/cloudevents+json' -Body '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"orderId": "100"}}' -Uri 'http://localhost:3601/v1.0/publish/order-pub-sub/orders'

{{% /codetab %}}

{{< /tabs >}}

Event deduplication

When using cloud events created by Dapr, the envelope contains an id field which can be used by the app to perform message deduplication. Dapr does not handle deduplication automatically. Dapr supports using message brokers that natively enable message deduplication.

Next steps

  • Learn why you might [not want to use CloudEvents]({{< ref pubsub-raw.md >}})
  • Try out the [pub/sub Quickstart]({{< ref pubsub-quickstart.md >}})
  • List of [pub/sub components]({{< ref setup-pubsub >}})
  • Read the [API reference]({{< ref pubsub_api.md >}})