You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/event-grid/concepts-event-grid-namespaces.md
+3-151Lines changed: 3 additions & 151 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,158 +43,10 @@ Here's a sample event:
43
43
### Another kind of event
44
44
The user community also refers as "events" to messages that carry a data point, such as a single device reading or a click on a web application page. That kind of event is usually analyzed over a time window to derive insights and take an action. In Event Grid’s documentation, we refer to that kind of event as a **data point**, **streaming data**, or simply as **telemetry**. Among other types of messages, this kind of events is used with Event Grid’s Message Queuing Telemetry Transport (MQTT) broker feature.
45
45
46
-
## CloudEvents
47
-
Event Grid namespace topics accepts events that comply with the Cloud Native Computing Foundation (CNCF)’s open standard [CloudEvents 1.0](https://github.com/cloudevents/spec) specification using the [HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) with [JSON format](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md). A CloudEvent is a kind of message that contains what is being communicated, referred to as event data, and metadata about it. The event data in event-driven architectures typically carries the information announcing a system state change. The CloudEvents metadata is composed of a set of attributes that provide contextual information about the message like where it originated (the source system), its type, etc. All valid messages adhering to the CloudEvents specifications must include the following required [context attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#required-attributes):
46
+
## Support for CloudEvents
47
+
Event Grid namespace topics accepts events that comply with the Cloud Native Computing Foundation (CNCF)’s open standard [CloudEvents 1.0](https://github.com/cloudevents/spec) specification using the [HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) with [JSON format](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md). A CloudEvent is a kind of message that contains what is being communicated, referred to as event data, and metadata about it. The event data in event-driven architectures typically carries the information announcing a system state change. The CloudEvents metadata is composed of a set of attributes that provide contextual information about the message like where it originated (the source system), its type, etc.
The CloudEvents specification also defines [optional](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#optional-attributes) and [extension context attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#extension-context-attributes) that you can include when using Event Grid.
55
-
56
-
When using Event Grid, CloudEvents is the preferred event format because of its well-documented use cases ([modes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#13-content-modes) for transferring events, [event formats](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#14-event-formats), etc.), extensibility, and improved interoperability. CloudEvents improves interoperability by providing a common event format for publishing and consuming events. It allows for uniform tooling and standard ways of routing & handling events.
57
-
58
-
### CloudEvents content modes
59
-
60
-
The CloudEvents specification defines three [content modes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#13-content-modes): [binary](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#31-binary-content-mode), [structured](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#32-structured-content-mode), and [batched](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#33-batched-content-mode).
61
-
62
-
>[!IMPORTANT]
63
-
> With any content mode you can exchange text (JSON, text/*, etc.) or binary-encoded event data. The binary content mode is not exclusively used for sending binary data.
64
-
65
-
The content modes aren't about the encoding you use, binary, or text, but about how the event data and its metadata are described and exchanged. The structured content mode uses a single structure, for example, a JSON object, where both the context attributes and event data are together in the HTTP payload. The binary content mode separates context attributes, which are mapped to HTTP headers, and event data, which is the HTTP payload encoded according to the media type set in ```Content-Type```.
66
-
67
-
### CloudEvents support
68
-
69
-
This table shows the current support for CloudEvents specification:
|[Structured JSON batched](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#33-batched-content-mode)| Yes, for publishing events |
75
-
|[Binary](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#31-binary-content-mode)| Yes, for publishing events|
76
-
77
-
The maximum allowed size for an event is 1 MB. Events over 64 KB are charged in 64-KB increments.
78
-
79
-
### Structured content mode
80
-
81
-
A message in CloudEvents structured content mode has both the context attributes and the event data together in an HTTP payload.
82
-
83
-
>[!Important]
84
-
> Currently, Event Grid supports the [CloudEvents JSON format](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md) with HTTP.
85
-
86
-
Here's an example of a CloudEvents in structured mode using the JSON format. Both metadata (all attributes that aren't "data") and the message/event data (the "data" object) are described using JSON. Our example includes all required context attributes along with some optional attributes (`subject`, `time`, and `datacontenttype`) and extension attributes (`comexampleextension1`, `comexampleothervalue`).
87
-
88
-
```json
89
-
{
90
-
"specversion" : "1.0",
91
-
"type" : "com.yourcompany.order.created",
92
-
"source" : "/orders/account/123",
93
-
"subject" : "O-28964",
94
-
"id" : "A234-1234-1234",
95
-
"time" : "2018-04-05T17:31:00Z",
96
-
"comexampleextension1" : "value",
97
-
"comexampleothervalue" : 5,
98
-
"datacontenttype" : "application/json",
99
-
"data" : {
100
-
"orderId" : "O-28964",
101
-
"URL" : "https://com.yourcompany/orders/O-28964"
102
-
}
103
-
}
104
-
```
105
-
106
-
You can use the JSON format with structured content to send event data that isn't a JSON value. To that end, you do the following steps:
107
-
108
-
1. Include a ```datacontenttype``` attribute with the media type in which the data is encoded.
109
-
1. If the media type is encoded in a text format like ```text/plain```, ```text/csv```, or ```application/xml```, you should use a ```data``` attribute with a JSON string containing what you are communicating as value.
110
-
1. If the media type represents a binary encoding, you should use a ```data_base64``` attribute whose value is a [JSON string](https://tools.ietf.org/html/rfc7159#section-7) containing the [BASE64](https://tools.ietf.org/html/rfc4648#section-4) encoded binary value.
111
-
112
-
For example, this CloudEvent carries event data encoded in ```application/protobuf``` to exchange Protobuf messages.
For more information on the use of the ```data``` or ```data_base64``` attributes, see [Handling of data](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md#31-handling-of-data) .
127
-
128
-
For more information about this content mode, see the CloudEvents [HTTP structured content mode specifications](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#32-structured-content-mode) .
129
-
130
-
### Batched content mode
131
-
132
-
Event Grid currently supports the [JSON batched content mode](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md#4-json-batch-format) when **publishing** CloudEvents to Event Grid. This content mode uses a JSON array filled with CloudEvents in structured content mode. For example, your application can publish two events using an array like the following. Likewise, if you're using Event Grid's [data plane SDK](https://azure.github.io/azure-sdk/releases/latest/java.html), this payload is also what is being sent:
133
-
134
-
```json
135
-
[
136
-
{
137
-
"specversion": "1.0",
138
-
"id": "E921-1234-1235",
139
-
"source": "/mycontext",
140
-
"type": "com.example.someeventtype",
141
-
"time": "2018-04-05T17:31:00Z",
142
-
"data": "some data"
143
-
},
144
-
{
145
-
"specversion": "1.0",
146
-
"id": "F555-1234-1235",
147
-
"source": "/mycontext",
148
-
"type": "com.example.someeventtype",
149
-
"time": "2018-04-05T17:31:00Z",
150
-
"data": {
151
-
"somekey" : "value",
152
-
"someOtherKey" : 9
153
-
}
154
-
}
155
-
]
156
-
```
157
-
158
-
For more information, see CloudEvents [Batched Content Mode](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#33-batched-content-mode) specs.
159
-
160
-
### Batching
161
-
162
-
Your application should batch several events together in an array to attain greater efficiency and higher throughput with a single publishing request. Batches can be up to 1 MB and the maximum size of an event is 1 MB.
163
-
164
-
### Binary content mode
165
-
166
-
A CloudEvent in binary content mode has its context attributes described as HTTP headers. The names of the HTTP headers are the name of the context attribute prefixed with ```ce-```. The ```Content-Type``` header reflects the media type in which the event data is encoded.
167
-
168
-
>[!IMPORTANT]
169
-
> When using the binary content mode the ```ce-datacontenttype``` HTTP header MUST NOT also be present.
170
-
171
-
>[!IMPORTANT]
172
-
> If you are planning to include your own attributes (i.e. extension attributes) when using the binary content mode, make sure that their names consist of lower-case letters ('a' to 'z') or digits ('0' to '9') from the ASCII character and that they do not exceed 20 characters in length. That is, the naming convention for [naming CloudEvents context attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#attribute-naming-convention) is more restrictive than that of valid HTTP header names. Not every valid HTTP header name is a valid extension attribute name.
173
-
174
-
The HTTP payload is the event data encoded according to the media type in ```Content-Type```.
175
-
176
-
An HTTP request used to publish a CloudEvent in content binary mode can look like this example:
Binary data according to protobuf encoding format. No context attributes are included.
191
-
```
192
-
193
-
### When to use CloudEvents' binary or structured content mode
194
-
195
-
You could use structured content mode if you want a simple approach for forwarding CloudEvents across hops and protocols. Since a CloudEvent in structured content mode contains the message together with its metadata, it's easy for clients to consume it as a whole and forward it to other systems.
196
-
197
-
You could use binary content mode if you know downstream applications require only the message without any extra information (that is, the context attributes). While with structured content mode you can still get the event data (message) out of the CloudEvent, it's easier if a consumer application just has it in the HTTP payload. For example, other applications can use other protocols and may be interested only in your core message, not its metadata. In fact, the metadata could be relevant just for the immediate first hop. In this case, having the data that you want to exchange apart from its metadata lends itself to easier handling and forwarding.
49
+
For more information, see [Support for CloudEvents schema](namespaces-cloud-events.md).
0 commit comments