Intern Azure Web PubSub-tjänst

Artikel
08/21/2024

Azure Web PubSub Service är ett enkelt sätt att publicera/prenumerera meddelanden med enkla WebSocket-anslutningar .

Klienter kan skrivas på valfritt språk som har stöd för Websocket.
Både text- och binärmeddelanden stöds inom en anslutning.
Med ett enkelt protokoll kan klienter publicera massage direkt till varandra.
Tjänsten hanterar WebSocket-anslutningar åt dig.

Villkor

Tjänst: Azure Web PubSub Service.

Anslutning: En anslutning, även kallad en klient eller en klientanslutning, är en logisk relation mellan en klient och Web PubSub-tjänsten. Via en "anslutning" deltar klienten och tjänsten i en serie tillståndskänsliga interaktioner. Anslutningar som använder olika protokoll kan bete sig annorlunda, till exempel är vissa anslutningar begränsade till varaktigheten för en nätverksanslutning, medan andra kan sträcka sig över flera efterföljande nätverksanslutningar mellan en klient och tjänsten.
Hubb: En hubb är ett logiskt begrepp för en uppsättning klientanslutningar. Vanligtvis använder du en hubb för ett scenario, till exempel en chatthubb eller en meddelandehubb . När en klientanslutning ansluter ansluter den till en hubb och under sin livslängd tillhör den hubben. När en klientanslutning ansluter till hubben finns hubben. Olika program kan dela en Azure Web PubSub-tjänst med hjälp av olika hubbnamn. Det finns ingen strikt gräns för antalet hubbar, men en hubb förbrukar mer tjänstbelastning jämfört med en grupp. Vi rekommenderar att du har en fördefinierad uppsättning hubbar i stället för att generera dem dynamiskt.
Grupp: En grupp är en delmängd av anslutningar till hubben. Du kan lägga till en klientanslutning till en grupp eller ta bort klientanslutningen från gruppen när du vill. När en klient till exempel ansluter till ett chattrum eller när en klient lämnar chattrummet kan det här chattrummet betraktas som en grupp. En klient kan ansluta till flera grupper och en grupp kan innehålla flera klienter. Gruppen är som en grupp "session", gruppsessionen skapas när någon ansluter till gruppen och sessionen är borta när ingen är i gruppen. Meddelanden som skickas till gruppen levereras till alla klienter som är anslutna till gruppen.
Användare: Anslutningar till Web PubSub kan tillhöra en användare. En användare kan ha flera anslutningar, till exempel när en enskild användare är ansluten över flera enheter eller flera webbläsarflikar.
Meddelande: När klienten är ansluten kan den skicka meddelanden till det överordnade programmet eller ta emot meddelanden från det överordnade programmet via WebSocket-anslutningen. Meddelanden kan vara i oformaterad text, binärt eller JSON-format och ha en maximal storlek på 1 MB.
Klienthändelser: Händelser skapas under livscykeln för en klientanslutning. En enkel WebSocket-klientanslutning skapar till exempel en connect händelse när den försöker ansluta till tjänsten, en connected händelse när den har anslutits till tjänsten, en message händelse när den skickar meddelanden till tjänsten och en disconnected händelse när den kopplas från tjänsten. Information om klienthändelser visas i avsnittet Klientprotokoll .
Händelsehanterare: Händelsehanteraren innehåller logiken för att hantera klienthändelserna. Registrera och konfigurera händelsehanterare i tjänsten via portalen eller Azure CLI i förväg. Information beskrivs i avsnittet Händelsehanterare .
Händelselyssnare(förhandsversion): Händelselyssnaren lyssnar bara på klienthändelserna men kan inte påverka livslängden för dina klienter genom deras svar. Information beskrivs i avsnittet Händelselyssnare .
Server: Servern kan hantera klienthändelser, hantera klientanslutningar eller publicera meddelanden till grupper. Både händelsehanterare och händelselyssnare anses vara serversidan. Information om servern beskrivs i avsnittet Serverprotokoll .

Arbetsflöde

Diagram som visar arbetsflödet för Web PubSub-tjänsten.

Arbetsflöde som visas i diagrammet ovan:

En klient ansluter till tjänstslutpunkten /client med hjälp av WebSocket-transport. Tjänsten vidarebefordrar varje WebSocket-ram till den konfigurerade överordnade (servern). WebSocket-anslutningen kan ansluta till valfri anpassad delprotokol som servern ska hantera, eller ansluta till den delprotokol json.webpubsub.azure.v1som stöds av tjänsten, vilket gör det möjligt för klienterna att göra pub/sub direkt. Information beskrivs i klientprotokollet.
Vid olika klienthändelser anropar tjänsten servern med hjälp av CloudEvents-protokollet. CloudEvents är en standardiserad och protokollagnostisk definition av strukturen och metadatabeskrivningen för händelser som hanteras av Cloud Native Computing Foundation (CNCF). Detaljerad implementering av CloudEvents-protokollet förlitar sig på serverrollen, som beskrivs i serverprotokollet.
Web PubSub-servern kan anropa tjänsten med hjälp av REST-API:et för att skicka meddelanden till klienter eller för att hantera anslutna klienter. Information beskrivs i serverprotokollet

Klientprotokoll

En klientanslutning ansluter till /client slutpunkten för tjänsten med hjälp av WebSocket-protokollet. WebSocket-protokollet tillhandahåller fullständiga duplex-kommunikationskanaler över en enda TCP-anslutning och standardiserades av IETF som RFC 6455 2011. De flesta språk har inbyggt stöd för att starta WebSocket-anslutningar.

Vår tjänst stöder två typer av klienter:

En kallas för den enkla WebSocket-klienten
Den andra kallas PubSub WebSocket-klienten

Den enkla WebSocket-klienten

En enkel WebSocket-klient, som namngivningen anger, är en enkel WebSocket-anslutning. Den kan också ha sin anpassade underprotokol.

I JS kan till exempel en enkel WebSocket-klient skapas med hjälp av följande kod.

// 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"
);

En enkel WebSocket-klient följer en klient-serverarkitektur<>, som följande sekvensdiagram visar: Diagram som visar sekvensen för en klientanslutning.

När klienten startar en WebSocket-handskakning försöker tjänsten anropa connect händelsehanteraren för WebSocket-handskakning. Utvecklare kan använda den här hanteraren för att hantera WebSocket-handskakningen, fastställa vilken delprotokol som ska användas, autentisera klienten och ansluta klienten till grupper.
När klienten har anslutits anropar tjänsten en connected händelsehanterare. Det fungerar som ett meddelande och blockerar inte klienten från att skicka meddelanden. Utvecklare kan använda den här hanteraren för att lagra data och kan svara med meddelanden till klienten. Tjänsten skickar också en connected händelse till alla som rör händelselyssnare, om någon.
När klienten skickar meddelanden utlöser tjänsten en message händelse till händelsehanteraren. Den här händelsen innehåller de meddelanden som skickas i en WebSocket-ram. Koden måste skicka meddelandena i den här händelsehanteraren. Om händelsehanteraren returnerar en icke-behuccessful-svarskod släpper tjänsten klientanslutningen. Tjänsten skickar även en message händelse till alla berörda händelselyssnare, om någon. Om tjänsten inte kan hitta några registrerade servrar för att ta emot meddelanden, tar tjänsten även bort klientanslutningen.
När klienten kopplas från försöker tjänsten utlösa disconnected händelsen till händelsehanteraren när den upptäcker frånkopplingen. Tjänsten skickar också en disconnected händelse till alla som rör händelselyssnare, om någon.

Scenarier

Dessa anslutningar kan användas i en typisk klient-serverarkitektur där klienten skickar meddelanden till servern och servern hanterar inkommande meddelanden med hjälp av händelsehanterare. Det kan också användas när kunder tillämpar befintliga underprotokoler i sin programlogik.

PubSub WebSocket-klienten

Tjänsten stöder också en specifik delprotokol med namnet json.webpubsub.azure.v1, som ger klienterna möjlighet att publicera/prenumerera direkt i stället för en tur och retur till den överordnade servern. Vi anropar WebSocket-anslutningen med json.webpubsub.azure.v1 subprotocol som PubSub WebSocket-klient. Mer information finns i Web PubSub-klientspecifikationen på GitHub.

I JS kan till exempel en PubSub WebSocket-klient skapas med hjälp av följande kod.

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

En PubSub WebSocket-klient kan:

Gå med i en grupp, till exempel:

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

Lämna en grupp, till exempel:

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

Publicera meddelanden till en grupp, till exempel:

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

Skicka anpassade händelser till den överordnade servern, till exempel:

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

PubSub WebSocket Subprotocol innehåller information om delprotokolen json.webpubsub.azure.v1 .

Du har märkt att för en enkel WebSocket-klient är servern en måste ha roll för att ta emot message händelserna från klienterna. En enkel WebSocket-anslutning utlöser alltid en message händelse när den skickar meddelanden och förlitar sig alltid på serversidan för att bearbeta meddelanden och utföra andra åtgärder. Med hjälp av delprotokolen json.webpubsub.azure.v1 kan en auktoriserad klient ansluta en grupp och publicera meddelanden till en grupp direkt. Den kan också dirigera meddelanden till olika händelsehanterare/händelselyssnare genom att anpassa händelsen som meddelandet tillhör.

Scenarier

Sådana klienter kan användas när klienter vill prata med varandra. Meddelanden skickas från client2 till tjänsten och tjänsten levererar meddelandet direkt till client1 om klienterna har behörighet att göra det.

Klient 1:

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",
    })
  );
};

Klient 2:

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"
    });
};

Som exemplet ovan visar client2 skickar du data direkt till genom att client1 publicera meddelanden Group1 som client1 finns i.

Sammanfattning av klienthändelser

Klienthändelser delas in i två kategorier:

Synkrona händelser (blockering) Synkrona händelser blockerar klientarbetsflödet.
- connect: Den här händelsen är endast avsedd för händelsehanterare. När klienten startar en WebSocket-handskakning utlöses händelsen och utvecklare kan använda connect händelsehanteraren för att hantera WebSocket-handskakningen, fastställa den delprotokol som ska användas, autentisera klienten och ansluta klienten till grupper.
- message: Den här händelsen utlöses när en klient skickar ett meddelande.
Asynkrona händelser (icke-blockerande) Asynkrona händelser blockerar inte klientarbetsflödet. I stället skickar de ett meddelande till servern. När en sådan händelseutlösare misslyckas loggar tjänsten felinformationen.
- connected: Den här händelsen utlöses när en klient ansluter till tjänsten.
- disconnected: Den här händelsen utlöses när en klient kopplas från med tjänsten.

Gräns för klientmeddelande

Den maximala tillåtna meddelandestorleken för en WebSocket-ram är 1 MB.

Klientautentisering

Arbetsflöde för autentisering

Klienten använder en signerad JWT-token för att ansluta till tjänsten. Överordnad kan också avvisa klienten när den är connect händelsehanterare för den inkommande klienten. Händelsehanteraren autentiserar klienten genom att userId ange och som roleklienten har i webhookssvaret eller neka klienten med 401. Avsnittet Händelsehanterare beskriver det i detalj.

I följande diagram beskrivs arbetsflödet.

Diagram som visar arbetsflödet för klientautentisering.

En klient kan endast publicera till andra klienter när den har behörighet . Klientens roles avgör de initiala behörigheter som klienten har:

Roll	Behörighet
Har inte angetts	Klienten kan skicka händelser.
`webpubsub.joinLeaveGroup`	Klienten kan ansluta/lämna valfri grupp.
`webpubsub.sendToGroup`	Klienten kan publicera meddelanden till valfri grupp.
`webpubsub.joinLeaveGroup.<group>`	Klienten kan ansluta/lämna gruppen `<group>`.
`webpubsub.sendToGroup.<group>`	Klienten kan publicera meddelanden för att gruppera `<group>`.

Serversidan kan också bevilja eller återkalla behörigheter för klienten dynamiskt via serverprotokoll som ska visas i ett senare avsnitt.

Serverprotokoll

Serverprotokollet tillhandahåller funktioner för servern för att hantera klienthändelser och hantera klientanslutningarna och grupperna.

I allmänhet innehåller serverprotokollet tre roller:

Händelsehanterare
Anslutningshanteraren
Händelselyssnare

Händelsehanterare

Händelsehanteraren hanterar inkommande klienthändelser. Händelsehanterare registreras och konfigureras i tjänsten via portalen eller Azure CLI. När en klienthändelse utlöses kan tjänsten identifiera om händelsen ska hanteras eller inte. Nu använder PUSH vi läget för att anropa händelsehanteraren. Händelsehanteraren på serversidan exponerar en offentligt tillgänglig slutpunkt för tjänsten att anropa när händelsen utlöses. Den fungerar som en webhook.

Web PubSub-tjänsten levererar klienthändelser till den överordnade webhooken med hjälp av HTTP-protokollet CloudEvents.

För varje händelse formulerar tjänsten en HTTP POST-begäran till den registrerade överordnade och förväntar sig ett HTTP-svar.

Data som skickas från tjänsten till servern är alltid i CloudEvents-format binary .

Diagram som visar push-läge för Web PubSub-tjänstens händelse.

Uppströms och validering

Händelsehanterare måste registreras och konfigureras i tjänsten via portalen eller Azure CLI innan de används. När en klienthändelse utlöses kan tjänsten identifiera om händelsen måste hanteras eller inte. För offentlig förhandsversion använder PUSH vi läget för att anropa händelsehanteraren. Händelsehanteraren på serversidan exponerar offentligt tillgänglig slutpunkt för tjänsten att anropa när händelsen utlöses. Den fungerar som en webhook uppströms.

URL:en kan använda {event} parametern för att definiera en URL-mall för webhookshanteraren. Tjänsten beräknar värdet för webhook-URL:en dynamiskt när klientbegäran kommer in. När en begäran /client/hubs/chat till exempel kommer in, med ett konfigurerat händelsehanterar-URL-mönster http://host.com/api/{event} för hubben chat, när klienten ansluter, kommer den först ATT SKICKA till den här URL:en: http://host.com/api/connect. Det här beteendet kan vara användbart när en PubSub WebSocket-klient skickar anpassade händelser, att händelsehanteraren hjälper till att skicka olika händelser till olika överordnade händelser. Parametern {event} tillåts inte i URL-domännamnet.

När du konfigurerar händelsehanteraren uppströms via Azure-portalen eller CLI följer tjänsten CloudEvents missbruksskydd för att verifiera den överordnade webhooken. Begärandehuvudet WebHook-Request-Origin är inställt på tjänstdomännamnet xxx.webpubsub.azure.comoch förväntar sig att svaret innehåller det WebHook-Allowed-Origin här domännamnet.

När du utför verifieringen matchas parametern {event} till validate. När du till exempel försöker ange URL:en till http://host.com/api/{event}försöker tjänsten ange ALTERNATIV för en begäran till http://host.com/api/validate och endast när svaret är giltigt kan konfigurationen ställas in.

För tillfället stöder vi inte WebHook-Request-Rate och WebHook-Request-Callback.

Autentisering/auktorisering mellan tjänst och webhook

Tänk på följande alternativ och steg för att upprätta säker autentisering och auktorisering mellan din tjänst och webhook:

Anonymt läge
Enkel autentisering som code tillhandahålls via den konfigurerade Webhook-URL:en.
Använd Microsoft Entra-auktorisering. Mer information finns i hur du använder hanterad identitet för mer information.

Aktivera identitet för tjänsten Web PubSub.
Välj från befintligt Microsoft Entra-program som står för din webhook-webbapp.

Anslutningshanteraren

Servern är av naturen en behörig användare. Med hjälp av händelsehanterarrollen känner servern till exempel connectionId till klienternas metadata och userId, så att den kan:

Stäng en klientanslutning
Skicka meddelanden till en klient
Skicka meddelanden till klienter som tillhör samma användare
Lägga till en klient i en grupp
Lägga till klienter som autentiseras som samma användare i en grupp
Ta bort en klient från en grupp
Ta bort klienter som autentiserats som samma användare från en grupp
Publicera meddelanden till en grupp

Den kan också bevilja eller återkalla publicerings-/kopplingsbehörigheter för en PubSub-klient:

Bevilja publicerings-/kopplingsbehörigheter till en viss grupp eller till alla grupper
Återkalla publicerings-/kopplingsbehörigheter för en viss grupp eller för alla grupper
Kontrollera om klienten har behörighet att ansluta eller publicera till en viss grupp eller till alla grupper

Tjänsten tillhandahåller REST-API:er för att servern ska utföra anslutningshantering.

Diagram som visar arbetsflödet för anslutningshanteraren för Web PubSub-tjänsten.

Det detaljerade REST API-protokollet definieras här.

Händelselyssnare

Kommentar

Funktionen för händelselyssnare är i förhandsversion.

Händelselyssnaren lyssnar på inkommande klienthändelser. Varje händelselyssnare innehåller ett filter för att ange vilka typer av händelser det gäller, en slutpunkt om var händelserna ska skickas.

För närvarande stöder vi Event Hubs som en slutpunkt för händelselyssnare.

Du måste registrera händelselyssnare i förväg, så att när en klienthändelse utlöses kan tjänsten skicka händelsen till motsvarande händelselyssnare. I det här dokumentet finns information om hur du konfigurerar en händelselyssnare med en händelsehubbslutpunkt.

Du kan konfigurera flera händelselyssnare. I vilken ordning du konfigurerar dem påverkas inte deras funktioner. Om en händelse matchar flera lyssnare skickas händelsen till alla matchande lyssnare. Se följande diagram för ett exempel. Om du till exempel konfigurerar fyra händelselyssnare samtidigt bearbetar varje lyssnare som tar emot en matchning händelsen. En klienthändelse som matchar med tre av dessa lyssnare skickas till tre lyssnare, där den återstående lyssnaren ignoreras.

Exempel på dataflödesdiagram för händelselyssnare

Du kan kombinera en händelsehanterare och händelselyssnare för samma händelse. I det här fallet får både händelsehanterare och händelselyssnare händelsen.

Web PubSub-tjänsten levererar klienthändelser till händelselyssnare med hjälp av CloudEvents AMQP-tillägget för Azure Web PubSub.

Sammanfattning

Händelsehanterarrollen hanterar kommunikation från tjänsten till servern medan chefsrollen hanterar kommunikation från servern till tjänsten. När du har kombinerat de två rollerna ser dataflödet mellan tjänsten och servern ut ungefär som i följande diagram med hjälp av HTTP-protokollet.

Diagram som visar det dubbelriktade arbetsflödet för Web PubSub-tjänsten.