Freigeben über

Azure Event Grid-Namespaces – Unterstützung für das CloudEvents-Schema

  • Artikel

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.

CloudEvents-Inhaltsmodus

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.

CloudEvents Support

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.

Strukturierter Inhaltsmodus

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, timeund 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:

  1. Fügen Sie ein datacontenttype Attribut mit dem Medientyp hinzu, in dem die Daten codiert sind.
  2. Wenn der Medientyp in einem Textformat wie text/plain, text/csvoder application/xml, codiert ist, sollten Sie ein data Attribut mit einer JSON-Zeichenfolge verwenden, die die Kommunikation als Wert enthält.
  3. 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_base64Umgang mit Daten.

Weitere Informationen zu diesem Inhaltsmodus finden Sie in den Spezifikationen des CloudEvents HTTP-strukturierten Inhaltsmodus.

Gebündelter 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.

Batchverarbeitung

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.

Binärinhaltsmodus

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-Typecodiert 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.

Gründe für die Verwendung des binär- oder strukturierten Inhaltsmodus von CloudEvents

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.

Zugehöriger Inhalt