Delen via

WebSocket-clientprotocollen voor Azure Web PubSub

  • Artikel

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:

  1. 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.
  2. De toepassingsserver retourneert de JWT en de service-URL naar de client.
  3. De client probeert verbinding te maken met de Web PubSub-service met behulp van de URL en het JWT-token dat is geretourneerd door 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 het JWT-token:

Beschrijving Claimtype Claimwaarde Opmerkingen
De userId voor de clientverbinding 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 rolwaarde die is 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 group de groep waaraan moet worden toegevoegd Geef meerdere 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')

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-antwoord

De PubSub WebSocket-client ondersteunt ackId eigenschap voorjoinGroup, sendToGroup leaveGroupen event berichten. Wanneer u deze ackIdgebruikt, kunt u een ack-antwoordbericht ontvangen wanneer uw aanvraag wordt verwerkt. U kunt ervoor kiezen om in brand- en vergeetscenario's weg te laten ackId . In het artikel beschrijven we de gedragsverschillen tussen het opgeven ackId of niet.

Gedrag wanneer er geen opgegeven is ackId

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 opgegeven

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 een ack-antwoord ackId=5met ackId=5 en niet ontvangt, probeert de client opnieuw en verzendt hetzelfde bericht opnieuw. In sommige gevallen is het bericht al brokered en gaat het ack-antwoord om een of andere reden verloren. De service weigert de nieuwe poging en beantwoordt een ack-antwoord met Duplicate reden.

Ack-antwoord

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 aanvraag wordt gekoppeld.

  • success is een bool en geeft aan of de aanvraag is verwerkt door de service. Als dat het is false, moeten clients de error.

  • error bestaat alleen wanneer success dit het geval is false en clients moeten verschillende 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. De client moet 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

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

Laten we bijvoorbeeld een JWT-token ondertekenen dat 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 client met de connect gebeurtenis-handler

De rollen van de clients kunnen ook worden ingesteld wanneer de connect gebeurtenis-handler is geregistreerd en de upstream-gebeurtenis-handler de client kan retourneren roles naar de Web PubSub-service bij het verwerken 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" });

Volgende stappen

Gebruik deze resources om te beginnen met het bouwen van uw eigen toepassing:

Zelfstudie: Berichten publiceren en abonneren op berichten in Azure Web PubSub

Zelfstudie: Een eenvoudige chatroom maken met Azure Web PubSub

Zelfstudie: Een door de service ondersteund subprotocol gebruiken voor clientstreaming

Zelfstudie: Serverloze chat bouwen met Azure Functions en Web PubSub

Zelfstudie: Een gebeurtenislistener configureren

Spelen met live demo's

Meer Voorbeelden van Azure Web PubSub verkennen