Azure Web PubSub unterstütztes JSON-WebSocket-Unterprotokoll

Artikel
10/26/2023

Das JSON WebSocket-Unterprotocol ermöglicht json.webpubsub.azure.v1den Austausch von Veröffentlichungs-/Abonnieren-Nachrichten zwischen Clients über den Dienst ohne Roundtrip zum Upstreamserver. Eine WebSocket-Verbindung mit dem json.webpubsub.azure.v1 Unterprotocol wird als PubSub WebSocket-Client bezeichnet.

Überblick

Eine einfache WebSocket-Verbindung löst ein message Ereignis aus, wenn es Nachrichten sendet und auf der Serverseite zum Verarbeiten von Nachrichten und anderen Vorgängen basiert.

Mit dem json.webpubsub.azure.v1 Unterprotocol können Sie PubSub WebSocket-Clients erstellen, die:

Teilnehmen an einer Gruppe mithilfe von Beitrittsanforderungen.
Veröffentlichen Sie Nachrichten mithilfe von Veröffentlichungsanforderungen direkt in einer Gruppe.
Weiterleiten von Nachrichten an verschiedene upstream-Ereignishandler mithilfe von Ereignisanforderungen.

Sie können beispielsweise einen PubSub WebSocket-Client mit dem folgenden JavaScript-Code erstellen:

// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');

In diesem Dokument werden die Unterprotocolanforderungen json.webpubsub.azure.v1 und -antworten beschrieben. Sowohl eingehende als auch ausgehende Datenframes müssen JSON-Nutzlasten enthalten.

Berechtigungen

Ein PubSub WebSocket-Client kann nur auf anderen Clients veröffentlicht werden, wenn er autorisiert ist. Der roles dem Client zugewiesene Legt die Berechtigungen fest, die dem Client gewährt werden:

Role	Berechtigung
Nicht angegeben	Der Client kann Ereignisanforderungen senden.
`webpubsub.joinLeaveGroup`	Der Client kann einer beliebigen Gruppe beitreten/diese verlassen.
`webpubsub.sendToGroup`	Der Client kann Nachrichten in einer beliebigen Gruppe veröffentlichen.
`webpubsub.joinLeaveGroup.<group>`	Der Client kann der Gruppe `<group>`beitreten/verlassen.
`webpubsub.sendToGroup.<group>`	Der Client kann Nachrichten in der Gruppe `<group>`veröffentlichen.

Der Server kann Clientberechtigungen dynamisch über REST-APIs oder Server-SDKs erteilen oder widerrufen.

Requests

Gruppen beitreten

Format:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}

ackId ist die Identität jeder Anforderung und sollte eindeutig sein. Der Dienst sendet eine ack-Antwortnachricht, um den Prozess über das Ergebnis der Anforderung zu informieren. Weitere Informationen finden Sie unter "AckId" und "Ack Response".

Gruppen verlassen

Format:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}

ackId ist die Identität jeder Anforderung und sollte eindeutig sein. Der Dienst sendet eine ack-Antwortnachricht, um den Prozess über das Ergebnis der Anforderung zu informieren. Weitere Informationen finden Sie unter "AckId" und "Ack Response".

Veröffentlichen von Nachrichten

Format:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}

ackId ist die Identität jeder Anforderung und sollte eindeutig sein. Der Dienst sendet eine ack-Antwortnachricht, um den Prozess über das Ergebnis der Anforderung zu informieren. Weitere Informationen finden Sie unter "AckId" und "Ack Response".
noEcho ist optional. Wenn dieser Wert auf "true" festgelegt ist, wird diese Nachricht nicht an dieselbe Verbindung zurückgesendet. Wenn keine Festlegung erfolgt, ist der Standardwert FALSE.
dataTypekann auf json, oder textbinary:
- json: data kann ein beliebiger Typ sein, der von JSON unterstützt und in seinem jeweiligen Zustand veröffentlicht wird. Wenn dataType nicht angegeben ist, wird dieser Wert standardmäßig auf json festgelegt.
- text: data sollte im Zeichenfolgenformat vorliegen, und die Zeichenfolgendaten werden veröffentlicht.
- binary: data sollte im Base64-Format vorliegen, und die Binärdaten werden veröffentlicht.

Fall 1: Veröffentlichen von Textdaten:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}

Die Subprotocol-Clients erhalten Folgendes <group_name> :

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}

Die einfachen WebSocket-Clients erhalten <group_name> die Zeichenfolge text data.

Fall 2: Veröffentlichen von JSON-Daten:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}

Die Subprotocol-Clients erhalten Folgendes <group_name> :

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}

Die einfachen WebSocket-Clients erhalten <group_name> die serialisierte Zeichenfolge {"hello": "world"}.

Fall 3: Veröffentlichen von Binärdaten:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}

Die Subprotocol-Clients erhalten Folgendes <group_name> :

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}

Die einfachen WebSocket-Clients empfangen <group_name> die Binärdaten im Binären Frame.

Versenden von benutzerdefinierten Ereignissen

Format:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}

ackId ist die Identität jeder Anforderung und sollte eindeutig sein. Der Dienst sendet eine ack-Antwortnachricht, um den Prozess über das Ergebnis der Anforderung zu informieren. Weitere Informationen finden Sie unter "AckId" und "Ack Response".

dataType kann text, binary oder json sein.

json: Daten können beliebige Json-Typen sein und werden veröffentlicht, wie es ist; Der Standardwert ist json.
text: Daten sind im Zeichenfolgenformat, und die Zeichenfolgendaten werden veröffentlicht;
binary: Die Daten sind im Base64-Format, und die Binärdaten werden veröffentlicht;

Fall 1: Ereignis mit Textdaten versenden:

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

Der upstream-Ereignishandler empfängt Daten ähnlich wie:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

text data

Die Content-Type HTTP-Anforderung für CloudEvents ist text/plaintextder ZeitpunktdataType.

Fall 2: Ereignis mit JSON-Daten versenden:

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

Der upstream-Ereignishandler empfängt Daten ähnlich wie:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

{
    "hello": "world"
}

Die Content-Type http-Anforderung für CloudEvents lautet application/jsondataTypejson

Fall 3: Ereignis mit Binärdaten versenden:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_binary", 
}

Der upstream-Ereignishandler empfängt Daten ähnlich wie:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

binary

Die Content-Type HTTP-Anforderung für CloudEvents ist application/octet-streambinaryder ZeitpunktdataType. Der WebSocket-Frame kann entweder das text-Format für Textnachricht-Frames aufweisen oder UTF8-codierte Binärdateien für binary-Nachrichtframes enthalten.

Der Web PubSub-Dienst lehnt den Client ab, wenn die Nachricht nicht mit dem beschriebenen Format übereinstimmt.

Antworten

Nachrichtentypen, die vom Client empfangen werden, können wie folgt sein:

ack - Die Antwort auf eine Anforderung, die eine ackId.
message – Nachrichten von der Gruppe oder dem Server.
system – Nachrichten aus dem Web PubSub-Dienst.

Ack-Antwort

Wenn die Clientanforderung enthält ackId, gibt der Dienst eine Ack-Antwort für die Anforderung zurück. Der Client sollte den Ack-Mechanismus behandeln, indem er auf die Ack-Antwort mit einem asyncawait Vorgang wartet und einen Timeoutvorgang verwendet, wenn die Ack-Antwort in einem bestimmten Zeitraum nicht empfangen wird.

Format:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

Die Clientimplementierung SOLLTE immer überprüfen, ob das success ist true oder false zuerst, und dann nur den Fehler lesen, wenn success das ist false.

Reaktion auf die Nachricht

Clients können Nachrichten empfangen, die von einer Gruppe veröffentlicht wurden, der der Client beigetreten ist oder vom Server, der in einer Serververwaltungsrolle ausgeführt wird, Nachrichten an bestimmte Clients oder Benutzer sendet.

Wenn die Nachricht aus einer Gruppe stammt

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

Wenn die Nachricht vom Server stammt,

{
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

Fall 1: Senden der Daten `Hello World` an die Verbindung über die REST-API mit `Content-Type`=`text/plain`

Ein einfacher WebSocket-Client empfängt einen WebSocket-Textrahmen mit Daten: Hello World;

Ein PubSub WebSocket-Client empfängt:

{
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

Fall 2: Senden der Daten `{ "Hello" : "World"}` an die Verbindung über die REST-API mit `Content-Type`=`application/json`

Ein einfacher WebSocket-Client empfängt einen Text-WebSocket-Frame mit Zeichenfolgendaten: { "Hello" : "World"}.

Ein PubSub WebSocket-Client empfängt:

{
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

Wenn die REST-API eine Zeichenfolge Hello World mit application/json dem Inhaltstyp sendet, empfängt der einfache WebSocket-Client eine JSON-Zeichenfolge, die mit doppelten Anführungszeichen (") umschlossen wird"Hello World".

Fall 3: Senden der von Binärdaten an die Verbindung über die REST-API mit `Content-Type`=`application/octet-stream`

Ein einfacher WebSocket-Client empfängt einen binären WebSocket-Frame mit den Binärdaten.

Ein PubSub WebSocket-Client empfängt:

{
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

Systemantwort

Der Web PubSub-Dienst sendet systembezogene Nachrichten an Clients.

Verbunden

Die An den Client gesendete Nachricht, wenn der Client erfolgreich eine Verbindung herstellt:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

Verbindung getrennt

Die an den Client gesendete Nachricht, wenn der Server die Verbindung schließt, oder wenn der Dienst den Client ablehnt.

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

Nächste Schritte

Erstellen Sie mithilfe dieser Ressourcen Ihre eigene Anwendung:

Tutorial: Veröffentlichen und Abonnieren von Nachrichten in Azure Web PubSub

Tutorial: Erstellen eines einfachen Chatrooms mit Azure Web PubSub

Tutorial: Verwenden eines vom Dienst unterstützten Unterprotokolls für Clientstreaming

Tutorial: Erstellen eines serverlosen Chats mit Azure Functions und Web PubSub

Tutorial: Konfigurieren eines Ereignislisteners

Spielen mit Livedemos

Weitere Beispiele für Azure Web PubSub

Azure Web PubSub unterstütztes JSON-WebSocket-Unterprotokoll

Überblick

Berechtigungen

Requests

Gruppen beitreten

Gruppen verlassen

Veröffentlichen von Nachrichten

Fall 1: Veröffentlichen von Textdaten:

Fall 2: Veröffentlichen von JSON-Daten:

Fall 3: Veröffentlichen von Binärdaten:

Versenden von benutzerdefinierten Ereignissen

Fall 1: Ereignis mit Textdaten versenden:

Fall 2: Ereignis mit JSON-Daten versenden:

Fall 3: Ereignis mit Binärdaten versenden:

Antworten

Ack-Antwort

Reaktion auf die Nachricht

Fall 1: Senden der Daten Hello World an die Verbindung über die REST-API mit Content-Type=text/plain

Fall 2: Senden der Daten { "Hello" : "World"} an die Verbindung über die REST-API mit Content-Type=application/json

Fall 3: Senden der von Binärdaten an die Verbindung über die REST-API mit Content-Type=application/octet-stream

Systemantwort

Verbunden

Verbindung getrennt

Nächste Schritte

Zusätzliche Ressourcen

Fall 1: Senden der Daten `Hello World` an die Verbindung über die REST-API mit `Content-Type`=`text/plain`

Fall 2: Senden der Daten `{ "Hello" : "World"}` an die Verbindung über die REST-API mit `Content-Type`=`application/json`

Fall 3: Senden der von Binärdaten an die Verbindung über die REST-API mit `Content-Type`=`application/octet-stream`