WebSocket-Clientprotokolle für Azure Web PubSub

Artikel
03/05/2024

Clients stellen mithilfe des WebSocket-Standardprotokolls eine Verbindung mit Azure Web PubSub her.

Dienstendpunkte

Der Web PubSub-Dienst stellt zwei Arten von Endpunkten bereit, mit dem Clients eine Verbindung herstellen können:

/client/hubs/{hub}
/client/?hub={hub}

{hub} ist ein obligatorischer Parameter, der als Isolation für verschiedene Anwendungen fungiert. Sie können ihn entweder im Pfad oder in der Abfrage festlegen.

Autorisierung

Clients stellen eine Verbindung mit dem Dienst über ein JSON Web Token (JWT) her. Das Token kann entweder in der Abfragezeichenfolge als /client/?hub={hub}&access_token={token} oder im Authorization-Header als Authorization: Bearer {token} enthalten sein.

Es folgt ein allgemeiner Autorisierungsworkflow:

Der Client führt einen Aushandlungsvorgang mit Ihrem Anwendungsserver aus. Der Anwendungsserver enthält die Middleware für die Autorisierung, die die Anforderungen des Clients bearbeitet und ein JWT signiert, damit der Client eine Verbindung mit dem Dienst herstellen kann.
Der Anwendungsserver gibt das JWT und die Dienst-URL an den Client zurück.
Der Client versucht, eine Verbindung mit dem Web PubSub-Dienst herzustellen, indem er die URL und das JWT-Token verwendet, das vom Anwendungsserver zurückgegeben wird.

Unterstützte Ansprüche

Sie können auch Eigenschaften für die Clientverbindung konfigurieren, wenn Sie das Zugriffstoken generieren, indem Sie spezielle Ansprüche im JWT-Token angeben:

Beschreibung	Anspruchstyp	Anspruchswert	Notizen
`userId` für die Clientverbindung	`sub`	die userId	Es ist nur ein `sub`-Anspruch zulässig.
Die Lebensdauer des Token	`exp`	Die Ablaufzeit	Der `exp`-Anspruch (Ablaufzeit) gibt die Ablaufzeit an, ab oder nach der das Token NICHT für die Bearbeitung akzeptiert werden darf.
Die Berechtigungen, über die die Clientverbindung anfänglich verfügt	`role`	der in den Berechtigungen definierte Rollenwert	Geben Sie mehrere `role`-Ansprüche an, wenn der Client über mehrere Berechtigungen verfügt.
Die anfänglichen Gruppen, denen die Clientverbindung beitritt, sobald sie eine Verbindung mit Azure Web PubSub herstellt	`group`	die Gruppe, der beizutreten ist	Geben Sie mehrere `group`-Ansprüche an, wenn der Client mehreren Gruppen beitritt.

Sie können dem Zugriffstoken auch benutzerdefinierte Ansprüche hinzufügen, und diese Werte werden als claims-Eigenschaft im Upstreamanforderungstext für die Verbindung beibehalten.

Server-SDKs stellen APIs zum Generieren der Zugriffstoken für die Clients bereit.

Der einfache WebSocket-Client

Ein einfacher WebSocket-Client ist, wie der Name schon sagt, eine einfache WebSocket-Verbindung. Er kann zudem über ein eigenes benutzerdefiniertes Unterprotokoll verfügen.

In JavaScript können Sie z. B. mithilfe des folgenden Codes einen einfachen WebSocket-Client erstellen:

// simple WebSocket client1
var client1 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'custom.subprotocol')

PubSub-WebSocket-Client

Ein PubSub-WebSocket-Client ist der WebSocket-Client, der vom Azure Web PubSub-Dienst definierte Unterprotokolle verwendet:

json.webpubsub.azure.v1
protobuf.webpubsub.azure.v1

Mit dem vom Dienst unterstützten Unterprotokoll können die PubSub-WebSocket-Clients Nachrichten direkt in Gruppen veröffentlichen, wenn sie über die Berechtigungen verfügen.

`json.webpubsub.azure.v1`-Unterprotokoll

Hier finden Sie ausführliche Informationen zum JSON-Unterprotokoll.

Erstellen eines PubSub-WebSocket-Clients

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

Direktes Beitreten zu einer Gruppe über den Client

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

Direktes Senden von Nachrichten vom Client an eine Gruppe

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

`protobuf.webpubsub.azure.v1`-Unterprotokoll

Protokollpuffer (protobuf) ist ein sprachneutrales, plattformneutrales, auf Binärdaten basierendes Protokoll, das das Senden von Binärdaten vereinfacht. Protobuf stellt Tools zum Generieren von Clients für viele Sprachen wie z. B. Java, Python, Objective-C, C# und C++ zur Verfügung. Weitere Informationen zu Protobuf.

In JavaScript können Sie beispielsweise einen PubSub-WebSocket-Client mit einem protobuf-Unterprotokoll erstellen, indem Sie den folgenden Code verwenden:

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

Hier finden Sie ausführliche Informationen zum protobuf-Unterprotokoll.

AckId- und Ack-Antwort

Der PubSub-WebSocket-Client unterstützt die ackId-Eigenschaft für joinGroup-, leaveGroup-, sendToGroup- und event-Nachrichten. Wenn Sie ackId verwenden, können Sie eine ack-Antwortnachricht erhalten, wenn Ihre Anforderung verarbeitet wird. Sie können ackId in Fire-and-Forget-Szenarien (Auslösen und Vergessen) auslassen. In diesem Artikel beschreiben wir die Unterschiede im Verhalten, wenn ackId angegeben oder ausgelassen wurde.

Verhalten, wenn `ackId` nicht angegeben ist.

Wenn ackId nicht angegeben wird, wird Fire-and-Forget (Auslösen und Vergessen) verwendet. Selbst wenn bei der Übermittlung von Nachrichten Fehler auftreten, haben Sie keine Möglichkeit, benachrichtigt zu werden.

Verhalten, wenn `ackId` angegeben ist.

Idempotente Veröffentlichung

ackId ist eine uint64-Zahl und sollte innerhalb eines Clients mit der gleichen Verbindungs-ID eindeutig sein. Web PubSub Service zeichnet die ackId auf, und die Nachrichten mit derselben ackId werden wie dieselbe Nachricht behandelt. Der Dienst lehnt es ab, dieselbe Nachricht mehr als einmal zu übermitteln, was bei Wiederholungsversuchen nützlich ist, um doppelte Nachrichten zu vermeiden. Wenn ein Client z. B. eine Nachricht mit ackId=5 sendet und keine ack-Antwort mit ackId=5 erhält, versucht er es erneut und sendet dieselbe Nachricht noch einmal. In einigen Fällen wurde die Nachricht bereits vermittelt, und die Ack-Antwort ist aus irgendeinem Grund verloren gegangen. Der Dienst lehnt den Wiederholungsversuche ab und sendet eine Ack-Antwort mit dem Grund Duplicate.

Ack-Antwort

Der Web-PubSub-Dienst sendet eine ack-Antwort für jede Anforderung mit ackId.

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 ackId ordnet die Anforderung zu.
success ist ein boolescher Wert und gibt an, ob die Anforderung vom Dienst erfolgreich verarbeitet wurde. Wenn die Antwort false lautet, müssen Clients den error überprüfen.
error ist nur vorhanden, wenn success entsprechend false ist und Clients unterschiedliche Logik für verschiedene name-Instanzen aufweisen sollten. Sie sollten davon ausgehen, dass es in Zukunft möglicherweise mehr name-Typen gibt.
- Forbidden: Der Client verfügt nicht über die Berechtigung für die Anforderung. Dem Client müssen relevante Rollen hinzugefügt werden.
- InternalServerError: Im Dienst ist ein interner Fehler aufgetreten. Eine Wiederholung ist erforderlich.
- Duplicate: Die Nachricht mit derselben ackId wurde bereits vom Dienst verarbeitet.

Berechtigungen

Wie Sie wahrscheinlich in der früheren Beschreibung des PubSub WebSocket-Clients gesehen haben, kann ein Client nur dann für andere Clients veröffentlichen, wenn er dazu autorisiert ist. Die Berechtigungen eines Clients können beim Herstellen der Verbindung oder für die Dauer der Verbindung erteilt werden.

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

Die Berechtigung eines Clients kann auf verschiedene Weise erteilt werden:

1. Zuweisen der Rolle zum Client beim Generieren des Zugriffstokens

Der Client kann mit einem JWT-Token eine Verbindung mit dem Dienst herstellen. Die Tokenpayload kann Informationen wie die role des Clients enthalten. Wenn Sie das JWT-Token beim Client signieren, können Sie dem Client Berechtigungen erteilen, indem Sie dem Client bestimmte Rollen zuweisen.

Signieren Sie z. B. ein JWT-Token, das über die Berechtigung zum Senden von Nachrichten an group1 und group2 verfügt:

let token = await serviceClient.getClientAccessToken({
    roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});

2. Zuweisen der Rolle zum Client mit dem `connect`-Ereignishandler

Die Rollen der Clients können auch festgelegt werden, wenn der connect-Ereignishandler registriert wird, und der Upstreamereignishandler kann die roles des Clients an den Web-PubSub-Dienst zurückgeben, wenn die connect-Ereignisse behandelt werden.

In JavaScript können Sie z. B. das handleConnect-Ereignis dafür konfigurieren:

let handler = new WebPubSubEventHandler("hub1", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
    });
  },
});

3. Zuweisen der Rolle zum Client über REST-APIs oder Server-SDKs während der Laufzeit

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });