From 6626fd58278f905500943e3aeae7db86030817d9 Mon Sep 17 00:00:00 2001 From: Yaron Schneider Date: Wed, 17 May 2023 13:08:00 -0700 Subject: [PATCH] Add clarification for cloud events (#3417) * add clarification for cloud events Signed-off-by: yaron2 * update missing fields Signed-off-by: yaron2 * Update daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md Co-authored-by: Mark Fussell Signed-off-by: Yaron Schneider * Update daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md Co-authored-by: Mark Fussell Signed-off-by: Yaron Schneider * add custom fields note Signed-off-by: yaron2 --------- Signed-off-by: yaron2 Signed-off-by: Yaron Schneider Co-authored-by: Mark Fussell Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- .../pubsub/pubsub-cloudevents.md | 53 +++++++++++++------ 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md index 0138a0c5f..251d3f234 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md @@ -11,39 +11,43 @@ To enable message routing and provide additional context with each message, Dapr Dapr uses CloudEvents to provide additional context to the event payload, enabling features like: - Tracing -- Deduplication by message Id - Content-type for proper deserialization of event data +- Verification of sender application ## CloudEvents example -Dapr implements the following CloudEvents fields when creating a message topic. +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 an `orders` topic message sent by Dapr 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. +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. ```json { - "topic": "orders", - "pubsubname": "order_pub_sub", - "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01", - "tracestate": "", - "data": { + "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" + }, + "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" } ``` @@ -65,6 +69,19 @@ As another example of a v1.0 CloudEvent, the following shows data as XML content ## 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](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#required-attributes) 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 @@ -102,6 +119,10 @@ Invoke-RestMethod -Method Post -ContentType 'application/cloudevents+json' -Body {{< /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 >}})