Edit

CloudEvents extension for Azure Web PubSub event listener with AMQP protocol

  • Article

The Azure Web PubSub Service describes client events as CloudEvents. CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems.

The event listeners of the service listen to client events. Event Hubs is currently the only supported event listener endpoint, whose primary protocol is AMQP (Advanced Message Queueing Protocol). The Web PubSub service uses CloudEvents AMQP protocol binding to map CloudEvents to AMQP messages.

The data sent from service to server is always in CloudEvents binary format.

Web PubSub CloudEvents attribute extension

This extension defines the attributes used by Web PubSub for each event it produces.

The following table contains attributes mapping to the standard properties section of an AMQP message.

Name Description Example
content-type The RFC-2046 MIME type for the message's body application/json
message-id Uniquely defines a message in a Web PubSub service, in the format of "{connection-id}/{an integer generated by service}" 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db/1

The following table contains all the CloudEvents attributes mapping to the application properties section of an AMQP message. Each attribute name is prefixed with cloudEvents:.

Name Description Example
specversion Cloud events specification version, is always 1.0 1.0
source Indicates the hub and the connection ID where the event comes from, in the format "/hubs/{hub}/client/{connectionId}" /hubs/chat/client/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id An integer generated by the service, unique in the events from the same client connection 1
awpsversion Cloud events Azure Web PubSub specification version, is always 1.0 1.0
hub The hub name where the event comes from chat
eventname The name of the event connected
type The event type azure.webpubsub.sys.connect
connectionid The ID of the client connection 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time The time when the service send the event, in the format "yyyy-MM-ddTHH:mm:ssZ" 2021-01-01T00:00:00Z
userid* The ID of user user1
subprotocol* The subprotocol name json.webpubsub.azure.v1
connectionstate* Defines the state for the connection. You can reset the value in the response header of event handlers. For more information about connection state, see Web PubSub CloudEvents attributes. anystring

The "*" following the attribute name indicates the attribute is present only when the value isn't null or empty.

Events

This section shows the AMQP message body with the attribute values that depend on a specific client event type. Attribute values that don't depend on a client event type are omitted.

System connected event

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

The message body is always empty JSON.

{}

System disconnected event

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

The message body contains the reason the client disconnected.

{"reason":"{Reason}"}

User events message for the simple WebSocket clients

  • content-type: application/octet-stream for binary frame; text/plain for text frame;
  • cloudEvents:type: azure.webpubsub.user.message

Message body is what the client sends.

User custom event {custom_event} for PubSub WebSocket clients

  • content-type: application/octet-stream for binary frame; application/json for JSON frame; text/plain for text frame; application/x-protobuf for Protobuf frame;
  • cloudEvents:type: azure.webpubsub.user.<event_name>

The following cases show how to send events with different data content types and the received AMQP message bodies.

Case 1: send event with text data:

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

Received AMQP message body:

text data

Case 2: send event with JSON data:

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

Received AMQP message body:

{
    "hello": "world"
}

Case 3: send event with binary data:

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

Received AMQP message body:

<binary data>