Interne azure Web PubSub-service

Artikel
08/21/2024

Azure Web PubSub Service biedt een eenvoudige manier om berichten te publiceren/abonneren met behulp van eenvoudige WebSocket-verbindingen .

Clients kunnen worden geschreven in elke taal met WebSocket-ondersteuning.
Zowel tekst- als binaire berichten worden ondersteund binnen één verbinding.
Met een eenvoudig protocol kunnen clients massages rechtstreeks naar elkaar publiceren.
De service beheert de WebSocket-verbindingen voor u.

Voorwaarden

Service: Azure Web PubSub-service.

Verbinding: Een verbinding, ook wel een client- of clientverbinding genoemd, is een logische relatie tussen een client en de Web PubSub-service. Via een 'verbinding' voeren de client en de service een reeks stateful interacties uit. Verbindingen die verschillende protocollen gebruiken, gedragen zich mogelijk anders, bijvoorbeeld een bepaalde verbinding is beperkt tot de duur van een netwerkverbinding, terwijl andere verbindingen kunnen worden uitgebreid tussen meerdere opeenvolgende netwerkverbindingen tussen een client en de service.
Hub: Een hub is een logisch concept voor een set clientverbindingen. Meestal gebruikt u één hub voor één scenario, bijvoorbeeld een chathub of een Notification Hub. Wanneer een clientverbinding verbinding maakt, maakt deze verbinding met een hub en gedurende de levensduur behoort deze tot die hub. Zodra een clientverbinding verbinding maakt met de hub, bestaat de hub. Verschillende toepassingen kunnen één Azure Web PubSub-service delen met behulp van verschillende hubnamen. Hoewel er geen strikte limiet is voor het aantal hubs, verbruikt een hub meer servicebelasting vergeleken met een groep. Het wordt aanbevolen om een vooraf bepaalde set hubs te hebben in plaats van ze dynamisch te genereren.
Groep: Een groep is een subset van verbindingen met de hub. U kunt een clientverbinding toevoegen aan een groep of de clientverbinding verwijderen uit de groep, op elk gewenst moment. Wanneer een client bijvoorbeeld deelneemt aan een chatruimte of wanneer een client de chatruimte verlaat, kan deze chatruimte worden beschouwd als een groep. Een client kan lid worden van meerdere groepen en een groep kan meerdere clients bevatten. De groep is net als een groep 'sessie', de groepssessie wordt gemaakt zodra iemand deelneemt aan de groep en de sessie is verdwenen wanneer niemand zich in de groep bevindt. Berichten die naar de groep worden verzonden, worden bezorgd bij alle clients die zijn verbonden met de groep.
Gebruiker: Verbindingen met Web PubSub kunnen tot één gebruiker behoren. Een gebruiker kan meerdere verbindingen hebben, bijvoorbeeld wanneer één gebruiker is verbonden op meerdere apparaten of meerdere browsertabbladen.
Bericht: Wanneer de client is verbonden, kan deze berichten verzenden naar de upstream-toepassing of berichten ontvangen van de upstream-toepassing via de WebSocket-verbinding. Berichten kunnen een tekst zonder opmaak, binaire of JSON-indeling hebben en een maximale grootte hebben van 1 MB.
Client gebeurtenissen: gebeurtenissen worden gemaakt tijdens de levenscyclus van een clientverbinding. Met een eenvoudige WebSocket-clientverbinding wordt bijvoorbeeld een connect gebeurtenis gemaakt wanneer wordt geprobeerd verbinding te maken met de service, een connected gebeurtenis wanneer deze verbinding heeft gemaakt met de service, een message gebeurtenis wanneer deze berichten naar de service verzendt in de standaardmodus sendEvent en een disconnected gebeurtenis wanneer de verbinding met de service wordt verbroken. Details over clientgebeurtenissen worden geïllustreerd in de sectie Clientprotocol .
Gebeurtenis-handler: de gebeurtenis-handler bevat de logica voor het afhandelen van de client gebeurtenissen. Registreer en configureer gebeurtenis-handlers in de service via de portal of Azure CLI vooraf. Details worden beschreven in de sectie Gebeurtenis-handler .
Gebeurtenislistener (preview): de gebeurtenislistener luistert alleen naar de clientevenementen, maar kan de levensduur van uw clients niet verstoren via hun reactie. Details worden beschreven in de sectie Gebeurtenislistener .
Server: De server kan client gebeurtenissen verwerken, clientverbindingen beheren of berichten publiceren naar groepen. Zowel gebeurtenis-handler als gebeurtenislistener worden beschouwd als serverzijde. Details over de server worden beschreven in de sectie Serverprotocol .

Workflow

Diagram van de Web PubSub-servicewerkstroom.

Werkstroom zoals weergegeven in de bovenstaande grafiek:

Een client maakt verbinding met het service-eindpunt /client met behulp van WebSocket-transport. Service stuurt standaard elk WebSocket-frame door naar de geconfigureerde upstream(server), de WebSocket-verbinding kan verbinding maken met elk aangepast subprotocol dat de server kan verwerken. De client kan ook verbinding maken met de modus sendToGroup en elk WebSocket-frame verzenden naar een specifieke groep. De client kan ook verbinding maken met de door de service ondersteunde subprotocollen, die functies bieden, zoals het verzenden van gebeurtenissen naar uw upstream, het samenvoegen van groepen en het rechtstreeks verzenden van berichten naar groepen. Details worden beschreven in het clientprotocol.
Bij verschillende client gebeurtenissen roept de service de server aan met behulp van het CloudEvents-protocol. CloudEvents is een gestandaardiseerde en protocolagnostische definitie van de structuur en metagegevensbeschrijving van gebeurtenissen die worden gehost door de Cloud Native Computing Foundation (CNCF). Gedetailleerde implementatie van het CloudEvents-protocol is afhankelijk van de serverfunctie, zoals beschreven in het serverprotocol.
De Web PubSub-server kan de service aanroepen met behulp van de REST API om berichten naar clients te verzenden of om de verbonden clients te beheren. Details worden beschreven in serverprotocol

Clientprotocol

Een clientverbinding maakt verbinding met het /client eindpunt van de service met behulp van het WebSocket-protocol. Het WebSocket-protocol biedt full-duplex communicatiekanalen via één TCP-verbinding en is gestandaardiseerde door de IETF als RFC 6455 in 2011. De meeste talen bieden systeemeigen ondersteuning voor het starten van WebSocket-verbindingen.

Onze service ondersteunt twee soorten clients:

Een wordt de eenvoudige WebSocket-client genoemd
De andere heet de PubSub WebSocket-client

De eenvoudige WebSocket-client

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

In JS kan bijvoorbeeld een eenvoudige WebSocket-client worden gemaakt 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. De standaardmodus sendEvent volgt een client-serverarchitectuur<>, zoals in het onderstaande sequentiediagram wordt weergegeven: Diagram met de volgorde voor een clientverbinding.

Wanneer de client een WebSocket-handshake start, probeert de service de connect gebeurtenishandler voor WebSocket-handshake aan te roepen. Ontwikkelaars kunnen deze handler gebruiken om de WebSocket-handshake af te handelen, het subprotocol te bepalen dat moet worden gebruikt, de client te verifiëren en lid te worden van de client aan groepen.
Wanneer de client is verbonden, roept de service een connected gebeurtenis-handler aan. Het werkt als een melding en blokkeert niet dat de client berichten verzendt. Ontwikkelaars kunnen deze handler gebruiken om gegevensopslag uit te voeren en kunnen reageren met berichten naar de client. De service pusht ook een connected gebeurtenis naar alle betreffende gebeurtenislisteners, indien van toepassing.
Wanneer de client berichten verzendt, activeert de service een message gebeurtenis naar de gebeurtenis-handler. Deze gebeurtenis bevat de berichten die worden verzonden in een WebSocket-frame. Uw code moet de berichten in deze gebeurtenis-handler verzenden. Als de gebeurtenis-handler een niet-geslaagde antwoordcode retourneert, wordt de clientverbinding door de service wegvalt. De service pusht ook een message gebeurtenis naar alle betrokken gebeurtenislisteners, indien van toepassing. Als de service geen geregistreerde servers kan vinden om de berichten te ontvangen, wordt de clientverbinding ook door de service gehaald.
Wanneer de client de verbinding verbreekt, probeert de service de disconnected gebeurtenis te activeren naar de gebeurtenis-handler zodra de verbinding is gedetecteerd. De service pusht ook een disconnected gebeurtenis naar alle betreffende gebeurtenislisteners, indien van toepassing.

Scenario's

Deze verbindingen kunnen worden gebruikt in een typische clientserverarchitectuur waarbij de client berichten naar de server verzendt en de server binnenkomende berichten verwerkt met behulp van gebeurtenis-handlers. Het kan ook worden gebruikt wanneer klanten bestaande subprotocollen toepassen in hun toepassingslogica .

De PubSub WebSocket-client

De service ondersteunt ook een specifiek subprotocol dat wordt aangeroepen json.webpubsub.azure.v1, waardoor de clients rechtstreeks publiceren/abonneren in plaats van een retour naar de upstream-server. We noemen de WebSocket-verbinding met json.webpubsub.azure.v1 subprotocol een PubSub WebSocket-client. Zie de Web PubSub-clientspecificatie op GitHub voor meer informatie.

In JS kan bijvoorbeeld een PubSub WebSocket-client worden gemaakt met behulp van de volgende code.

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

Een PubSub WebSocket-client kan:

Neem deel aan een groep, bijvoorbeeld:

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

Een groep verlaten, bijvoorbeeld:

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

Berichten publiceren naar een groep, bijvoorbeeld:

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

Aangepaste gebeurtenissen verzenden naar de upstream-server, bijvoorbeeld:

{
  "type": "event",
  "event": "<event_name>",
  "data": { "hello": "world" }
}

PubSub WebSocket Subprotocol bevat de details van het json.webpubsub.azure.v1 subprotocol.

In de dafult-modus sendEvent van eenvoudige WebSocket-client is de server een must hebben om de message gebeurtenissen van clients te ontvangen. Een eenvoudige WebSocket-verbinding in sendEvent de modus activeert altijd een message gebeurtenis wanneer er berichten worden verzonden en is altijd afhankelijk van de serverzijde om berichten te verwerken en andere bewerkingen uit te voeren. De sendToGroup modus biedt clients alleen de mogelijkheid om berichten rechtstreeks naar groepen te publiceren zonder aanvragen naar de server te activeren, wat nog steeds beperkt is. json.webpubsub.azure.v1 met subprotocol kunnen clients veel meer doen zonder aanvragen naar de server te activeren. Met behulp hiervan kan een geautoriseerde client rechtstreeks lid worden van een groep en berichten naar een groep publiceren. Het kan ook berichten doorsturen naar verschillende gebeurtenis-handlers/gebeurtenislisteners door de gebeurtenis aan te passen waartoe het bericht behoort.

Scenario's

Dergelijke clients kunnen worden gebruikt wanneer klanten met elkaar willen praten. Berichten worden verzonden naar client2 de service en de service levert het bericht rechtstreeks aan client1 als de clients daartoe gemachtigd zijn.

Client1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Client2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

Zoals in het bovenstaande voorbeeld wordt weergegeven, client2 verzendt u gegevens rechtstreeks naar client1 door berichten te Group1 publiceren waarnaar zich client1 bevindt.

Samenvatting van clientevenementen

Clientgebeurtenissen vallen in twee categorieën:

Synchrone gebeurtenissen (blokkerende) Synchrone gebeurtenissen blokkeren de clientwerkstroom.
- connect: Deze gebeurtenis is alleen bedoeld voor de gebeurtenis-handler. Wanneer de client een WebSocket-handshake start, wordt de gebeurtenis geactiveerd en kunnen ontwikkelaars gebeurtenishandler gebruiken connect om de WebSocket-handshake af te handelen, het subprotocol te bepalen dat moet worden gebruikt, de client te verifiëren en lid te worden van de client aan groepen.
- message: deze gebeurtenis wordt geactiveerd wanneer een client een bericht verzendt.
Asynchrone gebeurtenissen (niet-blokkerende) Asynchrone gebeurtenissen blokkeren de clientwerkstroom niet. In plaats daarvan verzenden ze een melding naar de server. Wanneer een dergelijke gebeurtenistrigger mislukt, registreert de service de foutdetails.
- connected: deze gebeurtenis wordt geactiveerd wanneer een client verbinding maakt met de service.
- disconnected: deze gebeurtenis wordt geactiveerd wanneer een client de verbinding met de service heeft verbroken.

Limiet voor clientberichten

De maximaal toegestane berichtgrootte voor één WebSocket-frame is 1 MB.

Clientverificatie

Verificatiewerkstroom

Client gebruikt een ondertekend JWT-token om verbinding te maken met de service. De upstream kan de client ook weigeren wanneer het gebeurtenis-handler van de binnenkomende client is connect . De gebeurtenis-handler verifieert de client door de userId en de roles op te geven die de client heeft in het antwoord van de webhook of de client te weigeren met 401. In de sectie Gebeurtenis-handler wordt deze in detail beschreven.

In de volgende grafiek wordt de werkstroom beschreven.

Diagram met de werkstroom voor clientverificatie.

Een client kan alleen publiceren naar andere clients wanneer deze is gemachtigd voor. De roles van de client bepaalt de initiële machtigingen die de client heeft:

Role	Machtiging
Niet opgegeven	De client kan gebeurtenissen verzenden.
`webpubsub.joinLeaveGroup`	De client kan lid worden van elke groep of elke groep verlaten.
`webpubsub.sendToGroup`	De client kan berichten publiceren naar elke groep.
`webpubsub.joinLeaveGroup.<group>`	De client kan deelnemen aan/verlaten groep `<group>`.
`webpubsub.sendToGroup.<group>`	De client kan berichten naar groep `<group>`publiceren.

De serverzijde kan ook dynamisch machtigingen van de client verlenen of intrekken via het serverprotocol , zoals wordt geïllustreerd in een latere sectie.

Serverprotocol

Serverprotocol biedt de functionaliteit voor de server voor het afhandelen van client gebeurtenissen en het beheren van de clientverbindingen en de groepen.

Over het algemeen bevat het serverprotocol drie functies:

Gebeurtenishandler
Verbindingsbeheer
Gebeurtenislistener

Gebeurtenishandler

De gebeurtenis-handler verwerkt de binnenkomende client gebeurtenissen. Gebeurtenis-handlers worden geregistreerd en geconfigureerd in de service via de portal of Azure CLI. Wanneer een clientgebeurtenis wordt geactiveerd, kan de service bepalen of de gebeurtenis moet worden verwerkt of niet. Nu gebruiken PUSH we de modus om de gebeurtenis-handler aan te roepen. De gebeurtenis-handler aan de serverzijde maakt een openbaar toegankelijk eindpunt beschikbaar dat de service kan aanroepen wanneer de gebeurtenis wordt geactiveerd. Het fungeert als een webhook.

De Web PubSub-service levert clientevenementen aan de upstream-webhook met behulp van het HTTP-protocol van CloudEvents.

Voor elke gebeurtenis formuleert de service een HTTP POST-aanvraag naar de geregistreerde upstream en verwacht een HTTP-antwoord.

De gegevens die van de service naar de server worden verzonden, hebben altijd de indeling CloudEvents binary .

Diagram met de gebeurtenispushmodus van de Web PubSub-service.

Upstream en validatie

Gebeurtenis-handlers moeten worden geregistreerd en geconfigureerd in de service via de portal of Azure CLI voordat ze voor het eerst worden gebruikt. Wanneer een clientgebeurtenis wordt geactiveerd, kan de service bepalen of de gebeurtenis moet worden verwerkt of niet. Voor openbare preview gebruiken PUSH we de modus om de gebeurtenis-handler aan te roepen. De gebeurtenis-handler aan de serverzijde maakt openbaar toegankelijke eindpunten beschikbaar voor de service die moet worden aangeroepen wanneer de gebeurtenis wordt geactiveerd. Het fungeert als een webhook upstream.

De URL kan een parameter gebruiken {event} om een URL-sjabloon te definiëren voor de webhookhandler. De service berekent de waarde van de webhook-URL dynamisch wanneer de clientaanvraag binnenkomt. Wanneer een aanvraag /client/hubs/chat bijvoorbeeld binnenkomt, met een geconfigureerd url-patroon http://host.com/api/{event} voor de gebeurtenis-handler voor de hub chat, wordt deze eerst POST naar deze URL verzonden: http://host.com/api/connect. Dit gedrag kan nuttig zijn wanneer een PubSub WebSocket-client aangepaste gebeurtenissen verzendt, die de gebeurtenis-handler helpt bij het verzenden van verschillende gebeurtenissen naar verschillende upstreams. De {event} parameter is niet toegestaan in de URL-domeinnaam.

Bij het instellen van de gebeurtenis-handler upstream via Azure Portal of CLI volgt de service misbruikbeveiliging van CloudEvents om de upstream-webhook te valideren. De WebHook-Request-Origin aanvraagheader is ingesteld op de domeinnaam van de service xxx.webpubsub.azure.comen verwacht dat het antwoord met de header WebHook-Allowed-Origin deze domeinnaam bevat.

Bij het uitvoeren van de validatie wordt de {event} parameter omgezet in validate. Wanneer u bijvoorbeeld de URL http://host.com/api/{event}probeert in te stellen, probeert de service een aanvraag naar http://host.com/api/validate OPTIONS in te stellen en alleen wanneer het antwoord geldig is, kan de configuratie worden ingesteld.

Op dit moment bieden we geen ondersteuning voor WebHook-Request-Rate en WebHook-Request-Callback.

Verificatie/autorisatie tussen service en webhook

Overweeg de volgende opties en stappen om veilige verificatie en autorisatie tussen uw service en webhook tot stand te brengen:

Anonieme modus
Eenvoudige verificatie die code wordt geleverd via de geconfigureerde Webhook-URL.
Gebruik Microsoft Entra-autorisatie. Zie voor meer informatie hoe u beheerde identiteit gebruikt voor meer informatie.

Identiteit inschakelen voor de Web PubSub-service.
Selecteer een bestaande Microsoft Entra-toepassing die staat voor uw webhook-web-app.

Verbindingsbeheer

De server is van nature een geautoriseerde gebruiker. Met behulp van de functie gebeurtenis-handler kent de server bijvoorbeeld de metagegevens van de clients en connectionId userIdkan het volgende:

Een clientverbinding sluiten
Berichten verzenden naar een client
Berichten verzenden naar clients die tot dezelfde gebruiker behoren
Een client toevoegen aan een groep
Clients toevoegen die zijn geverifieerd als dezelfde gebruiker aan een groep
Een client uit een groep verwijderen
Clients verwijderen die zijn geverifieerd als dezelfde gebruiker uit een groep
Berichten publiceren naar een groep

Het kan ook publicatie-/joinmachtigingen verlenen of intrekken voor een PubSub-client:

Publicatie-/joinmachtigingen verlenen aan een bepaalde groep of aan alle groepen
Publicatie-/joinmachtigingen intrekken voor een bepaalde groep of voor alle groepen
Controleer of de client gemachtigd is om lid te worden of te publiceren naar een bepaalde groep of naar alle groepen

De service biedt REST API's voor de server om verbindingsbeheer uit te voeren.

Diagram van de web pubsubserviceverbindingsbeheerwerkstroom.

Het gedetailleerde REST API-protocol wordt hier gedefinieerd.

Gebeurtenislistener

Notitie

De functie gebeurtenislistener is in preview.

De gebeurtenislistener luistert naar de binnenkomende client gebeurtenissen. Elke gebeurtenislistener bevat een filter om op te geven naar welke soorten gebeurtenissen het gaat, een eindpunt waar de gebeurtenissen naartoe moeten worden verzonden.

Momenteel ondersteunen we Event Hubs als een eindpunt voor gebeurtenislisteners.

U moet gebeurtenislisteners vooraf registreren, zodat wanneer een clientgebeurtenis wordt geactiveerd, de service de gebeurtenis naar de bijbehorende gebeurtenislisteners kan pushen. Raadpleeg dit document voor het configureren van een gebeurtenislistener met een Event Hub-eindpunt.

U kunt meerdere gebeurtenislisteners configureren. De volgorde waarin u ze configureert, heeft geen invloed op hun functionaliteit. Als een gebeurtenis overeenkomt met meerdere listeners, wordt de gebeurtenis verzonden naar alle overeenkomende listeners. Zie het volgende diagram voor een voorbeeld. Als u bijvoorbeeld vier gebeurtenislisteners tegelijk configureert, verwerkt elke listener die een overeenkomst ontvangt de gebeurtenis. Een clientgebeurtenis die overeenkomt met drie van deze listeners, wordt verzonden naar drie listeners, waarbij de resterende listener wordt genegeerd.

Voorbeeld van gebeurtenislistenergegevensstroomdiagram

U kunt een gebeurtenis-handler en gebeurtenislisteners combineren voor dezelfde gebeurtenis. In dit geval ontvangen zowel gebeurtenis-handler als gebeurtenislisteners de gebeurtenis.

De Web PubSub-service levert clientevenementen aan gebeurtenislisteners met behulp van de AMQP-extensie CloudEvents voor Azure Web PubSub.

Samenvatting

De rol gebeurtenis-handler verwerkt de communicatie van de service naar de server terwijl de managerfunctie communicatie van de server naar de service afhandelt. Zodra u de twee rollen combineert, ziet de gegevensstroom tussen de service en de server er ongeveer als volgt uit in het volgende diagram met behulp van het HTTP-protocol.

Diagram met de bidirectionele werkstroom van de Web PubSub-service.