WebSocket-clientprotocollen voor Azure Web PubSub

2025-04-03

Clients maken verbinding met Azure Web PubSub met behulp van het standaard WebSocket-protocol .

Service-eindpunten

De Web PubSub-service biedt twee typen eindpunten waarmee clients verbinding kunnen maken met:

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

{hub} is een verplichte parameter die fungeert als isolatie voor verschillende toepassingen. U kunt deze instellen in het pad of de query.

Autorisatie

Clients maken verbinding met de service met een JSON-webtoken (JWT). Het token kan zich in de querytekenreeks bevinden, als /client/?hub={hub}&access_token={token}, of in de Authorization header, als Authorization: Bearer {token}.

Hier volgt een algemene autorisatiewerkstroom:

De client onderhandelt met uw toepassingsserver. De toepassingsserver bevat de autorisatie-middleware, die de clientaanvraag afhandelt en een JWT ondertekent voor de client om verbinding te maken met de service.
De toepassingsserver retourneert de JWT en de service-URL naar de client.
De client probeert verbinding te maken met de Web PubSub-service met behulp van de URL en de JWT die is geretourneerd van de toepassingsserver.

Ondersteunde claims

U kunt ook eigenschappen voor de clientverbinding configureren bij het genereren van het toegangstoken door speciale claims op te geven in de JWT:

Beschrijving	claimtype	Claimwaarde	Opmerkingen
De `userId` voor de cliëntverbinding	`sub`	de userId	Er is slechts één `sub` claim toegestaan.
De levensduur van het token	`exp`	de verlooptijd	De `exp` claim (verlooptijd) identificeert de verlooptijd op of waarna het token NIET mag worden geaccepteerd voor verwerking.
De machtigingen die de clientverbinding aanvankelijk heeft	`role`	de waarde van de rol zoals gedefinieerd in machtigingen	Geef meerdere `role` claims op als de client meerdere machtigingen heeft.
De eerste groepen waaraan de clientverbinding wordt gekoppeld zodra deze verbinding maakt met Azure Web PubSub	`webpubsub.group`	de groep waaraan moet worden toegevoegd	Geef meerdere `webpubsub.group` claims op als de client lid wordt van meerdere groepen.

U kunt ook aangepaste claims toevoegen aan het toegangstoken en deze waarden blijven behouden als de claims eigenschap in de upstream-aanvraagbody.

Server-SDK's bieden API's voor het genereren van het toegangstoken voor de clients.

De eenvoudige WebSocket-client

Een eenvoudige WebSocket-client, zoals de naamgeving aangeeft, is een eenvoudige WebSocket-verbinding. Het kan ook een eigen aangepast subprotocol hebben.

In JavaScript kunt u bijvoorbeeld een eenvoudige WebSocket-client maken met behulp van de volgende code:

// 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')

Simple WebSocket-client heeft twee modi: sendEvent en sendToGroup. De modus wordt bepaald nadat de verbinding tot stand is gebracht en kan later niet meer worden gewijzigd.

sendEvent is de standaardmodus voor de eenvoudige WebSocket-client. In sendEvent de modus wordt elk WebSocket-frame beschouwd als een message gebeurtenis die door de client wordt verzonden. Gebruikers kunnen gebeurtenishandlers of gebeurtenislisteners configureren om deze message gebeurtenissen af te handelen.

// Every data frame is considered as a `message` event
var client3 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// Or explicitly set the mode
var client4 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendEvent');

In sendToGroup de modus wordt elk WebSocket-frame beschouwd als een bericht dat naar een specifieke groep moet worden gepubliceerd. group is een vereiste queryparameter in deze modus en slechts één waarde is toegestaan. De verbinding moet ook overeenkomende machtigingen hebben om berichten naar de doelgroep te verzenden. Zowel de rollen webpubsub.sendToGroup.<group> als webpubsub.sendToGroup dienen ervoor.

In JavaScript kunt u bijvoorbeeld een eenvoudige WebSocket-client maken in sendToGroup de modus met group=group1 behulp van de volgende code:

var client5 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendToGroup&group=group1');

De PubSub WebSocket-client

Een PubSub WebSocket-client is de WebSocket-client met behulp van subprotocollen die zijn gedefinieerd door de Azure Web PubSub-service:

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

Met het subprotocol dat door de service wordt ondersteund, kunnen de PubSub WebSocket-clientsberichten rechtstreeks publiceren naar groepen wanneer ze over de machtigingen beschikken.

Het `json.webpubsub.azure.v1` subprotocol

Kijk hier voor het JSON-subprotocol in detail.

Een PubSub WebSocket-client maken

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

Rechtstreeks lid worden van een groep vanaf de client

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

Berichten rechtstreeks vanaf de client naar een groep verzenden

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

Het `protobuf.webpubsub.azure.v1` subprotocol

Protocolbuffers (protobuf) is een taalneutraal, platformneutraal, binair protocol dat het verzenden van binaire gegevens vereenvoudigt. Protobuf biedt hulpprogramma's voor het genereren van clients voor veel talen, zoals Java, Python, Objective-C, C# en C++. Meer informatie over protobuf.

In JavaScript kunt u bijvoorbeeld een PubSub WebSocket-client maken met een protobuf-subprotocol met behulp van de volgende code:

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

Kijk hier voor het protobuf-subprotocol in detail.

AckId en Ack-reactie

De PubSub WebSocket-client ondersteunt ackId eigenschap voorjoinGroup, leaveGroupsendToGroupen event berichten. Wanneer u ackId gebruikt, kunt u een bevestigingsbericht ontvangen wanneer uw aanvraag wordt verwerkt. U kunt ervoor kiezen om ackId weg te laten in scenarios waarin u zich geen zorgen meer hoeft te maken. In het artikel beschrijven we de gedragsverschillen tussen het opgeven ackId of niet.

Gedrag wanneer er geen `ackId` is opgegeven

Als ackId dit niet is opgegeven, is het vuur-en-vergeet. Zelfs als er fouten optreden bij het brokeren van berichten, kunt u geen melding ontvangen.

Gedrag wanneer `ackId` gespecificeerd

Idempotent publiceren

ackId is een uint64-nummer en moet uniek zijn binnen een client met dezelfde verbindings-id. Web PubSub Service registreert de ackId en berichten met hetzelfde ackId bericht worden behandeld als hetzelfde bericht. De service weigert hetzelfde bericht meer dan één keer te brokeren, wat handig is bij het opnieuw proberen om dubbele berichten te voorkomen. Als een client bijvoorbeeld een bericht verzendt met ackId=5 en een ack-antwoord met ackId=5 niet ontvangt, probeert de client het opnieuw en verzendt hetzelfde bericht opnieuw. In sommige gevallen is het bericht al verwerkt en gaat het bevestigingsantwoord om welke reden dan ook verloren. De service weigert de nieuwe poging en beantwoordt een ack-antwoord met Duplicate reden.

Ack-reactie

Web PubSub Service verzendt ack-antwoord voor elke aanvraag met ackId.

Indeling:

{
    "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>"
    }
}

De ackId associeert de aanvraag.
success is een bool en geeft aan of de aanvraag is verwerkt door de service. Als false geldt, moeten klanten de error controleren.
error bestaat alleen wanneer successfalse is, en klanten moeten een andere logica hebben voor verschillende name. Stel dat er in de toekomst meer soorten name zijn.
- Forbidden: De client heeft niet de machtiging voor de aanvraag. Aan de client moeten relevante rollen worden toegevoegd.
- InternalServerError: Er is een interne fout opgetreden in de service. Opnieuw proberen is vereist.
- Duplicate: Het bericht met hetzelfde ackId bericht is al verwerkt door de service.

Machtigingen

Zoals u waarschijnlijk hebt opgemerkt in de eerdere beschrijving van de PubSub WebSocket-client, kan een client alleen publiceren naar andere clients wanneer dit is geautoriseerd . De machtigingen van een client kunnen worden verleend wanneer deze is verbonden of tijdens de levensduur van de verbinding.

Rol	Machtiging
Niet opgegeven	De client kan gebeurtenisaanvragen verzenden.
`webpubsub.joinLeaveGroup`	De client kan deelnemen aan of elke groep verlaten.
`webpubsub.sendToGroup`	De client kan berichten publiceren naar elke groep.
`webpubsub.joinLeaveGroup.<group>`	De client kan deelnemen aan of de groep `<group>`verlaten.
`webpubsub.sendToGroup.<group>`	De client kan berichten naar groep `<group>`publiceren.

De machtiging van een client kan op verschillende manieren worden verleend:

1. Wijs de rol toe aan de client bij het genereren van het toegangstoken

De client kan verbinding maken met de service met behulp van een JWT. De belasting van het token kan informatie bevatten, zoals de role van de client. Wanneer u de JWT aan de client ondertekent, kunt u machtigingen verlenen aan de client door de client specifieke rollen te geven.

Laten we bijvoorbeeld een JWT ondertekenen die de machtiging heeft om berichten te verzenden naar group1 en group2:

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

2. Wijs de rol toe aan de klant gebruikmakend van de `connect` eventhandler

De rollen van de clients kunnen ook worden ingesteld wanneer de connect gebeurtenissen-handler is geregistreerd en de upstream-gebeurtenissen-handler de roles van de client kan retourneren naar de Web PubSub-service bij het afhandelen van de connect gebeurtenissen.

In JavaScript kunt u bijvoorbeeld de handleConnect gebeurtenis zo configureren:

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. Wijs de rol toe aan de client via REST API's of server-SDK's tijdens runtime

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