Freigeben über

Azure Web PubSub unterstütztes JSON-WebSocket-Unterprotokoll

  • Artikel

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.

Übersicht

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:

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 dann auf anderen Clients veröffentlichen, wenn er dazu autorisiert ist. Die dem Client zugewiesenen roles bestimmen die Berechtigungen, 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/diese verlassen.
webpubsub.sendToGroup.<group> Der Client kann Nachrichten in der Gruppe <group> veröffentlichen.

Der Server kann dynamisch Clientberechtigungen ü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. Ausführliche Informationen finden Sie unter AckId- and Ack-Antwort

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. Ausführliche Informationen finden Sie unter AckId- and Ack-Antwort

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. Ausführliche Informationen finden Sie unter AckId- and Ack-Antwort
  • noEcho ist optional. Wenn dies auf „true“ festgelegt ist, wird diese Nachricht nicht an dieselbe Verbindung zurückgesendet. Wenn keine Festlegung erfolgt, ist der Standardwert FALSE.
  • dataType kann auf json, text oder binary festgelegt werden.
    • 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 Unterprotokollclients in <group_name> empfangen:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Die einfachen WebSocket-Clients in <group_name> empfangen die Zeichenfolge text data.

Fall 2: Veröffentlichen von JSON-Daten:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Die Unterprotokollclients in <group_name> empfangen:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Die einfachen WebSocket-Clients in <group_name> empfangen 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 Unterprotokollclients in <group_name> empfangen:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Die einfachen WebSocket-Clients in <group_name> empfangen die binären Daten 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. Ausführliche Informationen finden Sie unter AckId- and Ack-Antwort

dataType kann text, binary oder json sein.

  • json: Die Daten können ein beliebiger Typ sein, der von JSON unterstützt wird, und werden in ihrem jeweiligen Zustand veröffentlicht. Der Standardwert ist json.
  • text: Die Daten liegen im Zeichenfolgenformat vor, und die Zeichenfolgendaten werden veröffentlicht.
  • binary: Die Daten liegen im base64-Format vor, und die binären Daten werden veröffentlicht.

Fall 1: Ereignis mit Textdaten versenden:

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

Der Upstreamereignishandler 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

Content-Type für die CloudEvents-HTTP-Anforderung ist text/plain, wenn dataType den Wert text hat.

Fall 2: Ereignis mit JSON-Daten versenden:

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

Der Upstreamereignishandler 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"
}

Content-Type für die CloudEvents-HTTP-Anforderung ist application/json, wenn dataType den Wert json hat.

Fall 3: Ereignis mit Binärdaten versenden:

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

Der Upstreamereignishandler 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

Content-Type für die CloudEvents-HTTP-Anforderung ist application/octet-stream, wenn dataType den Wert binary hat. 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 dem beschriebenen Format entspricht.

Ping

Format:

{
    "type": "ping",
}

Der Client kann eine ping Nachricht an den Dienst senden, um den Web PubSub-Dienst zu aktivieren, um die Liveität des Clients zu erkennen.

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.
  • Pong - Die Antwort auf eine ping Nachricht.

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 async await 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 entweder von einer Gruppe empfangen, in die der Client eingebunden ist, oder vom Server. Dieser verwendet eine Serververwaltungsrolle und sendet Nachrichten an bestimmte Clients oder Benutzer.

  1. 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"
}

  2. 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-Textframe 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.

Pong-Antwort

Der Web PubSub-Dienst sendet eine pong Nachricht an den Client, wenn er eine ping Nachricht vom Client empfängt.

Format:

{
    "type": "pong",
}

Verbunden

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

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

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