CloudEvents-Erweiterung für den Azure Web PubSub-Ereignislistener mit AMQP-Protokoll

  • Artikel

Der Azure Web PubSub-Dienst beschreibt Clientereignisse als CloudEvents. CloudEvents ist eine Spezifikation zum Beschreiben von Ereignisdaten in gängigen Formaten, um die Interoperabilität zwischen Diensten, Plattformen und Systemen zu gewährleisten.

Die Ereignislistener des Diensts lauschen auf Clientereignisse. Event Hubs ist derzeit der einzige unterstützte Ereignislistenerendpunkt, dessen primäres Protokoll AMQP (Advanced Message Queueing Protocol) ist. Der Web PubSub-Dienst verwendet die AMQP-Protokollbindung von CloudEvents, um AMQP-Nachrichten CloudEvents zuzuordnen.

Die vom Dienst an den Server gesendeten Daten haben immer das CloudEvents-Format binary.

Web PubSub CloudEvents-Attributerweiterung

Diese Erweiterung definiert Attribute, die vom Web PubSub-Dienst für jedes von ihm erzeugte Ereignis verwendet werden.

Die folgende Tabelle enthält Attribute, die dem Abschnitt Standardeigenschaften einer AMQP-Nachricht zugeordnet sind.

Name Beschreibung des Dataflows Beispiel
content-type Der MIME-Typ „RFC-2046“ für den Nachrichtentext Anwendung/json
message-id Definiert eindeutig eine Nachricht in einem Web PubSub-Dienst im Format „{Verbindungs-ID}/{vom Dienst generierte ganze Zahl}“. 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db/1

Die folgende Tabelle enthält alle CloudEvents-Attribute, die dem Abschnitt Anwendungseigenschaften einer AMQP-Nachricht zugeordnet sind. Jedem Attributnamen wird das Präfix cloudEvents: vorangestellt.

Name Beschreibung des Dataflows Beispiel
specversion Version der Spezifikation für Cloudereignisse, immer 1.0 1.0
source Gibt den Hub und die Verbindungs-ID, von denen das Ereignis stammt, im Format „/hubs/{Hub}/client/{Verbindungs-ID}“ an. /hubs/chat/client/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id Eine vom Dienst generierte ganze Zahl, die in den Ereignissen der gleichen Clientverbindung eindeutig ist 1
awpsversion Version der Azure Web PubSub-Spezifikation für Cloudereignisse, immer 1.0 1.0
hub Der Hubname, von dem das Ereignis stammt Chat
eventname Der Name des Ereignisses connected
type Der Ereignistyp azure.webpubsub.sys.connect
connectionid Die ID der Clientverbindung 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time Der Zeitpunkt, zu dem der Dienst das Ereignis gesendet hat, im Format „yyyy-MM-ddTHH:mm:ssZ“ 2021-01-01T00:00:00Z
userid* Die ID des Benutzers user1
subprotocol* Der Name des Unterprotokolls json.webpubsub.azure.v1
connectionstate* Legt den Status der Verbindung fest. Sie können den Wert im Antwortheader von Ereignishandlern zurücksetzen. Weitere Informationen zum Verbindungsstatus finden Sie unter Attribute. anystring

Das auf den Attributnamen folgende Sternchen (*) gibt an, dass das Attribut nur vorhanden ist, wenn der Wert nicht NULL oder leer ist.

Ereignisse

In diesem Abschnitt wird der AMQP-Nachrichtentext mit den Attributwerten angezeigt, die von einem bestimmten Clientereignistyp abhängen. Attributwerte, die nicht von einem Clientereignistyp abhängen, werden weggelassen.

Systemconnectedereignis

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.connected
  • cloudEvents:eventname: connected

Der Nachrichtentext ist immer leerer JSON-Code.

{}

Systemdisconnectedereignis

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.disconnected
  • cloudEvents:eventname: disconnected

Der Nachrichtentext enthält den Grund, warum die Verbindung mit dem Client getrennt wurde.

{"reason":"{Reason}"}

Benutzerereignisse vom Typ message für einfache WebSocket-Clients

  • content-type: application/octet-stream für binären Frame; text/plain für Textframe;
  • cloudEvents:type: azure.webpubsub.user.message

Der Nachrichtentext besteht aus den vom Client gesendeten Informationen.

Benutzerdefiniertes Ereignis {custom_event} für PubSub WebSocket-Clients

  • content-type: application/octet-stream für binären Frame; application/json für JSON-Frame; text/plain für Textframe; application/x-protobuf für Protobuf-Frame
  • cloudEvents:type: azure.webpubsub.user.<event_name>

Die folgenden Fälle zeigen, wie Ereignisse mit unterschiedlichen Dateninhaltstypen und den empfangenen AMQP-Nachrichtentexten gesendet werden.

Fall 1: Ereignis mit Textdaten versenden:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "text",
    "data": "text data"
}

Empfangener AMQP-Nachrichtentext:

text data

Fall 2: Ereignis mit JSON-Daten versenden:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "json",
    "data": {
        "hello": "world"
     }
}

Empfangener AMQP-Nachrichtentext:

{
    "hello": "world"
}

Fall 3: Ereignis mit Binärdaten versenden:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

Empfangener AMQP-Nachrichtentext:

<binary data>