From 0804779f0102b1ed09b1be49bd2120228de2c1e2 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Thu, 29 Jun 2023 12:36:56 -0400 Subject: [PATCH] update per mark Signed-off-by: Hannah Hunter --- .../pubsub/pubsub-cloudevents.md | 90 +++++++++++++++---- 1 file changed, 75 insertions(+), 15 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 3764f2c86..b14958634 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 @@ -14,9 +14,15 @@ Dapr uses CloudEvents to provide additional context to the event payload, enabli - Content-type for proper deserialization of event data - Verification of sender application -## CloudEvents example +You can choose any of the three methods for publish a CloudEvent via pub/sub: -A publish operation to Dapr results in a cloud event envelope containing the following fields: +1. Write a pub/sub event, which is then automatically wrapped by Dapr in a CloudEvent envelope. +1. Retain the CloudEvents attributes automatically provided by Dapr while overriding any of the standard CloudEvent properties. +1. Supply your own full CloudEvent envelope. + +## Dapr-generated CloudEvents example + +Writing a publish operation to Dapr automatically wraps it in a CloudEvent envelope containing the following fields: - `id` - `source` @@ -30,7 +36,9 @@ A publish operation to Dapr results in a cloud event envelope containing the fol - `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. +The following example demonstrates a CloudEvent 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 { @@ -66,15 +74,9 @@ As another example of a v1.0 CloudEvent, the following shows data as XML content } ``` -{{% 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" >}}) +## Override Dapr-generated CloudEvents values -{{% /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: +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` @@ -85,22 +87,79 @@ When not provided, Dapr automatically generates several CloudEvent properties. Y 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" >}}): +### Example + +To override the `source` and `id` values from [the CloudEvent example above]({{< ref "#cloudevents-example" >}}) in code: + +{{< tabs "Python" ".NET" >}} + +{{% codetab %}} + +```python +with DaprClient() as client: + for i in range(1, 10): + order = {'orderId': i} + # Publish an event/message using Dapr PubSub + result = client.publish_event( + pubsub_name='order_pub_sub', + topic_name='orders', + publish_metadata={'cloudevent-id: 'd99b228f-6c73-4e78-8c4d-3f80a043d317', cloudevent-source: 'payment'} + ) +``` + +{{% /codetab %}} + + +{{% codetab %}} + +```csharp +for (int i = 1; i <= 10; i++) { + var order = new Order(i); + using var client = new DaprClientBuilder().Build(); + + // Override cloudevent metadata + var metadata = new Dictionary() { + { "cloudevent.source", "payment" }, + { "cloudevent.id", "d99b228f-6c73-4e78-8c4d-3f80a043d317" } + } + + // Publish an event/message using Dapr PubSub + await client.PublishEventAsync("order_pub_sub", "orders", order, metadata); + Console.WriteLine("Published data: " + order); + + await Task.Delay(TimeSpan.FromSeconds(1)); +} +``` + +{{% /codetab %}} + +{{< /tabs >}} + + +The JSON payload then reflects the new `source` and `id` values: + ```json { "topic": "orders", "pubsubname": "order_pub_sub", + "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01", + "tracestate": "", + "data": { + "orderId": 1 + }, + "id": "d99b228f-6c73-4e78-8c4d-3f80a043d317", "specversion": "1.0", "datacontenttype": "application/json; charset=utf-8", - "cloudevent-source": "checkout", - "cloudevent-type": "com.dapr.event.sent", + "source": "payment", + "type": "com.dapr.event.sent", "time": "2020-09-23T06:23:21Z", + "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01" } ``` {{% 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 >}}) +While you can 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 %}} @@ -108,6 +167,7 @@ While you can specify and then override `traceid`/`traceparent` and `tracestate` ## 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`