Azure Event Grid-Namespaces – Unterstützung für das CloudEvents-Schema
Event Grid-Namensraumthemen akzeptieren Ereignisse, die dem offenen Standard CloudEvents 1.0 der Cloud Native Computing Foundation (CNCF) entsprechen, unter Verwendung der HTTP-Protokollbindung mit JSON-Format. Eine CloudEvents-Instanz ist eine Art von Nachricht, die den zu übermittelnden Inhalt (als Ereignisdaten bezeichnet) und die dazugehörigen Metadaten enthält. Die Ereignisdaten in ereignisgesteuerten Architekturen enthalten in der Regel die Informationen, die eine Änderung des Systemzustands ankündigen. Die CloudEvents-Metadaten bestehen aus einer Reihe von Attributen, die kontextbezogene Informationen zu der Nachricht bereitstellen, z. B. woher sie stammt (das Quellsystem), der Typ usw. Alle gültigen Nachrichten, die den CloudEvents-Spezifikationen entsprechen, müssen die folgenden erforderlichen Kontextattributeenthalten:
Die CloudEvents-Spezifikation definiert auch optionale und erweiterte Kontextattribute, die Sie bei der Verwendung von Event Grid einbeziehen können.
Bei Verwendung von Event Grid ist CloudEvents aufgrund seiner gut dokumentierten Anwendungsfälle (Modi für die Übertragung von Ereignissen, Ereignisformaten usw.), seiner Erweiterbarkeit und der verbesserten Interoperabilität das bevorzugte Ereignisformat. CloudEvents verbessert die Interoperabilität, indem ein allgemeines Ereignisformat für die Veröffentlichung bereitgestellt wird und Ereignisse genutzt werden. Sie ermöglicht einheitliche Tools und Standardmethoden für das Routing und Behandeln von Ereignissen.
Die CloudEvents-Spezifikation definiert drei Inhaltsmodi: binär, strukturiertund gebündelt.
Wichtig
In jedem Inhaltsmodus können Sie Text (JSON, text/* usw.) oder binär codierte Ereignisdaten austauschen. Der Binärinhaltsmodus wird nicht ausschließlich zum Senden von Binärdaten verwendet.
Bei den Inhaltsmodi geht es nicht darum, welche Kodierung Sie verwenden, binär oder Text, sondern darum, wie die Ereignisdaten und ihre Metadaten beschrieben und ausgetauscht werden. Der strukturierte Inhaltsmodus verwendet eine einzelne Struktur, z. B. ein JSON-Objekt, bei dem sowohl die Kontextattribute als auch Ereignisdaten in der HTTP-Payload zusammen sind. Der binäre Inhaltsmodus trennt zwischen Kontextattributen, die auf HTTP-Header abgebildet werden, und Ereignisdaten, bei denen es sich um die HTTP-Payload handelt, die entsprechend dem in Content-Type
eingestellten Medientyp kodiert ist.
Die Tabelle zeigt die aktuelle Unterstützung für die CloudEvents-Spezifikation:
CloudEvents-Inhaltsmodus | Unterstützt? |
---|---|
Strukturiertes JSON-Format | Ja |
Strukturierte JSON-Format als Batch | Ja, für Veröffentlichungsereignisse |
Binär | Ja, für Veröffentlichungsereignisse |
Die maximal zulässige Größe für ein Ereignis beträgt 1 MB. Ereignisse, die größer als 64 KB sind, werden in Schritten von 64 KB in Rechnung gestellt.
Eine Nachricht im strukturierten CloudEvents-Inhaltsmodus weist sowohl die Kontextattribute als auch die Ereignisdaten in einer HTTP-Payload auf.
Wichtig
Derzeit unterstützt Event Grid das CloudEvents JSON-Format mit HTTP.
Hier ist ein Beispiel für ein CloudEvents im strukturierten Modus mit dem JSON-Format. Sowohl Metadaten (alle Attribute, die nicht „Daten“) als auch die Nachrichten-/Ereignisdaten (das „data“-Objekt) werden mithilfe von JSON beschrieben. Unser Beispiel enthält alle erforderlichen Kontextattribute zusammen mit einigen optionalen Attributen (subject
, time
und datacontenttype
) und Erweiterungsattributen (comexampleextension1
, comexampleothervalue
).
{
"specversion" : "1.0",
"type" : "com.yourcompany.order.created",
"source" : "/orders/account/123",
"subject" : "O-28964",
"id" : "A234-1234-1234",
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleothervalue" : 5,
"datacontenttype" : "application/json",
"data" : {
"orderId" : "O-28964",
"URL" : "https://com.yourcompany/orders/O-28964"
}
}
Sie können das JSON-Format mit strukturierten Inhalten verwenden, um Ereignisdaten zu senden, die kein JSON-Wert sind. Zu diesem Zweck führen Sie die folgenden Schritte aus:
- Fügen Sie ein
datacontenttype
Attribut mit dem Medientyp hinzu, in dem die Daten codiert sind. - Wenn der Medientyp in einem Textformat wie
text/plain
,text/csv
oderapplication/xml
, codiert ist, sollten Sie eindata
Attribut mit einer JSON-Zeichenfolge verwenden, die die Kommunikation als Wert enthält. - Wenn der Medientyp eine binäre Codierung darstellt, sollten Sie ein
data_base64
Attribut verwenden, dessen Wert eine JSON-Zeichenfolge ist, die den base64-codierten Binärwert enthält.
In diesem CloudEvent werden z. B. Ereignisdaten in application/protobuf
codiert, um Protobuf-Nachrichten auszutauschen.
{
"specversion" : "1.0",
"type" : "com.yourcompany.order.created",
"source" : "/orders/account/123",
"id" : "A234-1234-1234",
"time" : "2018-04-05T17:31:00Z",
"datacontenttype" : "application/protobuf",
"data_base64" : "VGhpcyBpcyBub3QgZW5jb2RlZCBpbiBwcm90b2J1ZmYgYnV0IGZvciBpbGx1c3RyYXRpb24gcHVycG9zZXMsIGltYWdpbmUgdGhhdCBpdCBpcyA6KQ=="
}
Weitere Informationen über die Verwendung von data
oder Attributen finden Sie unter data_base64
Umgang mit Daten.
Weitere Informationen zu diesem Inhaltsmodus finden Sie in den Spezifikationen des CloudEvents HTTP-strukturierten Inhaltsmodus.
Event Grid unterstützt derzeit den gebündelten JSON-Inhaltsmodus bei der Veröffentlichung von CloudEvents in Event Grid. Dieser Inhaltsmodus verwendet ein JSON-Array, das mit CloudEvents gefüllt ist, im strukturierten Inhaltsmodus. Ihre Anwendung kann z. B. zwei Ereignisse mithilfe eines Arrays wie der folgenden veröffentlichen. Ebenso gilt: Wenn Sie die Datenebene SDK von Event Grid verwenden, ist diese Payload auch das, was gesendet wird:
[
{
"specversion": "1.0",
"id": "E921-1234-1235",
"source": "/mycontext",
"type": "com.example.someeventtype",
"time": "2018-04-05T17:31:00Z",
"data": "some data"
},
{
"specversion": "1.0",
"id": "F555-1234-1235",
"source": "/mycontext",
"type": "com.example.someeventtype",
"time": "2018-04-05T17:31:00Z",
"data": {
"somekey" : "value",
"someOtherKey" : 9
}
}
]
Weitere Informationen finden Sie in den Spezifikationen für den gebündelten Inhaltsmodus von CloudEvents.
Ihre Anwendung sollte mehrere Ereignisse als Batch in einem Array zusammenfassen, um mit einer einzelnen Veröffentlichungsanforderung eine höhere Effizienz und einen höheren Durchsatz zu erzielen. Batches können bis zu 1 MB groß sein, und die maximal zulässige Größe eines Ereignisses beträgt 1 MB.
Ein CloudEvent im Binärinhaltsmodus weist seine Kontextattribute auf, die als HTTP-Header beschrieben werden. Die Namen der HTTP-Header sind der Name des Kontextattributes, dem das Präfix ce-
vorangestellt ist. Der Content-Type
Header gibt den Medientyp an, in dem die Ereignisdaten codiert sind.
Wichtig
Bei Verwendung des Binärinhaltsmodus darf der ce-datacontenttype
HTTP-Header NICHT ebenfalls vorhanden sein.
Wichtig
Wenn Sie eigene Attribute (d. h. Erweiterungsattribute) einfügen möchten, wenn Sie den binären Inhaltsmodus verwenden, stellen Sie sicher, dass deren Namen aus Kleinbuchstaben („a“ bis „z“) oder Ziffern („0“ bis „9“) des ASCII-Zeichensatzes bestehen und nicht länger als 20 Zeichen sind. Das heißt, die Namenskonvention für die Benennung von CloudEvents-Kontextattributen ist restriktiver als die der gültigen HTTP Header-Namen. Nicht jeder gültige Name eines HTTP-Headers ist auch ein gültiger Name für ein Erweiterungsattribut.
Die HTTP-Payload ist die Ereignisdaten, die gemäß dem Medientyp in Content-Type
codiert sind.
Eine HTTP-Anforderung, die zum Veröffentlichen eines CloudEvent im Binärmodus für Inhalte verwendet wird, kann wie im folgenden Beispiel aussehen:
POST / HTTP/1.1
HOST mynamespace.eastus-1.eventgrid.azure.net/topics/mytopic
ce-specversion: 1.0
ce-type: com.example.someevent
ce-source: /mycontext
ce-id: A234-1234-1234
ce-time: 2018-04-05T17:31:00Z
ce-comexampleextension1: value
ce-comexampleothervalue: 5
content-type: application/protobuf
Binary data according to protobuf encoding format. No context attributes are included.
Sie können den Modus für strukturierte Inhalte verwenden, wenn Sie einen einfachen Ansatz zum Weiterleiten von CloudEvents über Hops und Protokolle wünschen. Da eine CloudEvents-Instanz im strukturierten Inhaltsmodus die Nachricht zusammen mit den Metadaten enthält, ist es für Clients einfach, sie als Ganzes zu verarbeiten und an andere Systeme weiterzuleiten.
Sie können den Binärinhaltsmodus verwenden, wenn Sie wissen, dass nachgeschaltete Anwendungen nur die Nachricht ohne zusätzliche Informationen benötigen (d. a. die Kontextattribute). Mit dem Modus für strukturierte Inhalte können Sie zwar immer noch die Ereignisdaten (Nachricht) aus dem CloudEvent abrufen, aber es ist einfacher, wenn eine Anwendung für Verbraucher diese Daten nur in der HTTP-Payload hat. Beispielsweise können andere Anwendungen andere Protokolle verwenden und dabei nur an der Kernnachricht interessiert sein, nicht an den Metadaten. Tatsächlich könnten die Metadaten nur für den unmittelbaren ersten Hop relevant sein. In diesem Fall eignet sich die Verwendung der Daten, die Sie abgesehen von den Metadaten austauschen möchten, für eine einfachere Handhabung und Weiterleitung.
- Eine Einführung in Event Grid finden Sie unter Informationen zu Event Grid.
- Informationen zu den ersten Schritten bei der Verwendung von Namespacethemen finden Sie unter Veröffentlichen von Ereignissen mithilfe von Namespacethemen.