Interní služby Azure Web PubSub

Služba Azure Web PubSub poskytuje snadný způsob, jak publikovat nebo odebírat zprávy pomocí jednoduchých připojení WebSocket .

• Klienti můžou být napsaní v jakémkoli jazyce, který podporuje Protokol WebSocket.
• Textové i binární zprávy se podporují v rámci jednoho připojení.
• Jednoduchý protokol umožňuje klientům publikovat zprávy přímo mezi sebou.
• Služba spravuje připojení WebSocket za vás.

Podmínky

• Služba: Azure Web PubSub Service.

• Připojení: Připojení, označované také jako klient nebo připojení klienta, je to logický vztah mezi klientem a službou Web PubSub. Prostřednictvím "připojení" se klient a služba zapojují do řady stavových interakcí. připojení, které používají různé protokoly, se můžou chovat odlišně, například některá připojení jsou omezená na dobu trvání síťového připojení, zatímco jiné můžou přesahovat několik následných síťových připojení mezi klientem a službou.

• Centrum: Centrum je logický koncept sady klientských připojení. Obvykle používáte jedno centrum pro jeden scénář, například centrum chatu nebo centrum oznámení . Když se klient připojí, spojí se s hubem a během svého trvání patří k tomuto hubu. Jakmile se klientské připojení připojí k rozbočovači, rozbočovač je aktivní. Různé aplikace můžou sdílet jednu službu Azure Web PubSub pomocí různých názvů center. I když neexistuje žádný striktní limit počtu rozbočovačů, rozbočovač zatěžuje službu více než skupina. Doporučujeme mít předem určenou sadu rozbočovačů, a negenerovat je dynamicky.

• Skupina: Skupina je podmnožinou připojení k centru. Ke skupině můžete přidat připojení klienta nebo ho z této skupiny kdykoli odebrat. Když se například klient připojí k chatovací místnosti nebo když klient opustí chatovací místnost, může být tato chatovací místnost považována za skupinu. Klient se může připojit k více skupinám a skupina může obsahovat více klientů. Skupina funguje jako "session"; relace skupiny se vytvoří, jakmile se někdo připojí ke skupině, a relace zmizí, když ve skupině nikdo není. Zprávy odeslané skupině se doručí všem klientům připojeným ke skupině.

• Uživatel: Připojení k podsítě Web PubSub mohou patřit jednomu uživateli. Uživatel může mít více připojení, například když je jeden uživatel připojený na více zařízeních nebo na několika kartách prohlížeče.

• Zpráva: Když je klient připojen, může odesílat zprávy do upstreamové aplikace nebo přijímat zprávy z upstreamové aplikace prostřednictvím připojení WebSocket. Zprávy můžou být ve formátu prostého textu, binárního formátu nebo formátu JSON a mají maximální velikost 1 MB.

• Události klienta: Události se vytvářejí během životního cyklu připojení klienta. Například jednoduché připojení klienta WebSocket vytvoří connect událost, když se pokusí připojit ke službě, connected událost, když se úspěšně připojila ke službě, message událost, když odesílá zprávy do služby ve výchozím režimu sendEvent a disconnected událost, když se odpojí od služby. Podrobnosti o událostech klienta jsou znázorněny v části Protokol klienta.

• Obslužná rutina události obsahuje logiku pro zpracování událostí klienta. Zaregistrujte a nakonfigurujte obslužné rutiny událostí ve službě prostřednictvím portálu nebo Azure CLI předem. Podrobnosti jsou popsány v sekci Obslužná rutina události.

• Naslouchací proces událostí(Preview): Naslouchací proces událostí pouze naslouchá událostem klienta, ale nemůže ovlivňovat dobu života vašich klientů prostřednictvím jejich odpovědi. Podrobnosti jsou popsány v části Posluchač událostí.

• Server: Server může zpracovávat události klienta, spravovat připojení klientů nebo publikovat zprávy do skupin. Obslužná rutina události i naslouchací proces událostí se považují za serverovou stranu. Podrobnosti o serveru jsou popsány v části Protokol serveru .

Pracovní postup

Pracovní postup, jak je znázorněno v předchozím grafu:

1. Klient se připojí ke koncovému bodu služby /client pomocí přenosu WebSocket. Služba ve výchozím nastavení předává každý rámec WebSocketu na nakonfigurovaný upstream (server). WebSocketové připojení se může připojit k libovolnému vlastnímu podprotokolu, který server dokáže zpracovat. Případně se klient může připojit k režimu sendToGroup a odeslat každý rámec Protokolu WebSocket do konkrétní skupiny. Klient se také může připojit k podprotokolům podporovaným službou, které nabízejí funkce, jako je odesílání událostí do upstreamu, připojování skupin a přímé odesílání zpráv do skupin. Podrobnosti jsou popsány v klientském protokolu.
2. Při různých událostech klienta služba vyvolá server pomocí protokolu CloudEvents. CloudEvents je standardizovaná a protokolově nezávislá definice struktury a metadat popis událostí hostovaných platformou CNCF (Cloud Native Computing Foundation). Podrobná implementace protokolu CloudEvents závisí na roli serveru popsané v protokolu serveru.
3. Server Web PubSub může vyvolat službu pomocí rozhraní REST API k odesílání zpráv klientům nebo ke správě připojených klientů. Podrobnosti jsou popsány v protokolu serveru.

Klientský protokol

Klient se připojí k /client cílovému bodu služby pomocí WebSocket protokolu. Protokol WebSocket poskytuje plně duplexní komunikační kanály přes jediné připojení TCP a byl standardizován IETF jako RFC 6455 v roce 2011. Většina jazyků má nativní podporu pro spuštění připojení WebSocket.

Naše služba podporuje dva druhy klientů:

• Jeden se nazývá jednoduchý klient WebSocket.
• Druhý se nazývá Klient PubSub WebSocket.

Jednoduchý klient WebSocket

Jednoduchý klient WebSocket, jak již název napovídá, je jednoduché spojení WebSocket. Může mít také vlastní dílčí podprotokol.

Například v JS lze jednoduchý klient WebSocket vytvořit pomocí následujícího kódu.

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

Jednoduchý klient WebSocket má dva režimy. Jeho výchozí režim sendEvent se řídí architekturou klient-server<>, jak ukazuje následující sekvenční diagram:

1. Když klient spustí metodu handshake protokolu WebSocket, služba se pokusí vyvolat obslužnou rutinu události pro metodu connect handshake protokolu WebSocket. Vývojáři mohou tuto obslužnou rutinu použít ke zpracování metody handshake protokolu WebSocket, určení dílčího protokolu, který se má použít, ověření klienta a připojení klienta ke skupinám.
2. Po úspěšném připojení klienta vyvolá služba obslužnou rutinu události connected. Funguje jako oznámení a nezablokuje klientovi odesílání zpráv. Vývojáři můžou tuto obslužnou rutinu použít k ukládání dat a můžou reagovat na zprávy klientovi. Služba také odešle connected událost všem souvisejícím nasloucháčům událostí, pokud nějaké existují.
3. Když klient odesílá zprávy, služba aktivuje message událost obsluze událostí. Tato událost obsahuje zprávy odeslané v rámci WebSocket. Váš kód musí odesílat zprávy uvnitř této obslužné rutiny události. Pokud obslužná rutina události vrátí neúspěšný kód odpovědi, služba ukončí připojení klienta. Služba také odešle message událost všem příslušným naslouchacím procesům událostí( pokud existuje). Pokud služba nemůže najít žádné registrované servery pro příjem zpráv, služba také zahodí připojení klienta.
4. Když se klient odpojí, služba se pokusí aktivovat disconnected událost obslužné rutině události, jakmile zjistí odpojení. Služba také odešle disconnected událost všem příslušným posluchačům událostí, pokud existují.

Scénáře

Tato připojení se dají použít v typické architektuře klient-server, kde klient odesílá zprávy na server a server zpracovává příchozí zprávy pomocí obslužných rutin událostí. Dá se použít také v případech, kdy zákazníci ve své aplikační logice používají stávající subprotokoly.

Klient PubSub WebSocket

Služba také podporuje konkrétní dílčí název , json.webpubsub.azure.v1který umožňuje klientům provádět publikování a odběr přímo místo doby odezvy na nadřazený server. Zavoláme připojení WebSocket s json.webpubsub.azure.v1 subprotocol klienta PubSub WebSocket. Další informace najdete ve specifikaci klienta Web PubSub na GitHubu.

Například v JS je možné vytvořit klienta PubSub WebSocket pomocí následujícího kódu.

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

Klient PubSub WebSocket může:

• Připojte se ke skupině, například:

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

• Ponechte skupinu, například:

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

• Publikování zpráv do skupiny, například:

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

• Odesílání vlastních událostí na upstreamový server, například:

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

json.webpubsub.azure.v1.

V režimu sendEvent dafult jednoduchého klienta WebSocket je server musí mít roli pro příjem message událostí od klientů. Jednoduché připojení WebSocket v sendEvent režimu vždy aktivuje message událost při odesílání zpráv a vždy spoléhá na server na zpracování zpráv a provádění dalších operací. Režim sendToGroup umožňuje klientům publikovat zprávy do skupin přímo bez aktivace požadavků na server, což je stále omezené. json.webpubsub.azure.v1 subprotocol umožňuje klientům provádět mnohem více, aniž by aktivovaly požadavky na server. Díky tomu se autorizovaný klient může připojit ke skupině a publikovat zprávy přímo do skupiny. Může také směrovat zprávy do různých obslužných rutin událostí nebo naslouchacích procesů událostí přizpůsobením události , kterou zpráva patří.

Scénáře

Tyto klienty lze použít, když si klienti chtějí vzájemně komunikovat. Zprávy se odesílají do client2 služby a služba zprávu doručí přímo, client1 pokud k tomu mají klienti oprávnění.

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

Jak ukazuje výše uvedený příklad, client2 odesílá data přímo do client1 publikováním zpráv na Group1, ve kterém se client1 nachází.

Souhrn událostí klienta

Klientské události spadají do dvou kategorií:

• Synchronní události (blokující) Synchronní události blokují pracovní postup klienta.

  • connect: Tato událost je určena pouze pro obsluhu události. Když klient spustí metodu handshake protokolu WebSocket, aktivuje se událost a vývojáři můžou použít connect obslužnou rutinu události ke zpracování metody handshake protokolu WebSocket, určení subprotocolu, který se má použít, ověření klienta a připojení klienta ke skupinám.
  • message: Tato událost se aktivuje, když klient odešle zprávu.

• Asynchronní události (neblokující) Asynchronní události neblokují pracovní postup klienta. Místo toho posílají na server oznámení. Pokud takový trigger události selže, služba zaprotokoluje podrobnosti o chybě.

  • connected: Tato událost se aktivuje, když se klient úspěšně připojí ke službě.
  • disconnected: Tato událost se aktivuje, když se klient odpojí se službou.

Limit zpráv klienta

Maximální povolená velikost zprávy pro jeden rámec WebSocket je 1 MB.

Ověřování klientů

Pracovní postup ověřování

Klient používá pro připojení ke službě podepsaný webový token JSON (JWT). Upstream může také odmítnout klienta, když se connect jedná o obslužnou rutinu události příchozího klienta. Obslužná rutina události autentizuje klienta zadáním userId a role ve webhook odpovědi nebo odmítne klienta s chybou 401. Sekce obslužné rutiny události ji popisuje podrobněji.

Následující graf popisuje pracovní postup.

Klient může publikovat k jiným klientům pouze tehdy, když je autorizován. Z role klienta se určují počáteční oprávnění, která má klient.

Role	Oprávnění
Neurčeno	Klient může odesílat události.
webpubsub.joinLeaveGroup	Klient se může připojit nebo opustit libovolnou skupinu.
webpubsub.sendToGroup	Klient může publikovat zprávy do libovolné skupiny.
webpubsub.joinLeaveGroup.<group>	Klient se může připojit nebo opustit skupinu <group>.
webpubsub.sendToGroup.<group>	Klient může publikovat zprávy do skupiny <group>.

Na straně serveru můžete také dynamicky udělit nebo odvolat oprávnění klienta prostřednictvím protokolu serveru, jak je vidět v další části.

Protokol serveru

Protokol serveru poskytuje funkci pro server pro zpracování klientských událostí a správu připojení klientů a skupin.

Protokol serveru obecně obsahuje tři role:

1. Obslužná rutina události
2. Správce připojení
3. Posluchač událostí

Zpracovatel událostí

Obslužný program události obsluhuje příchozí události klienta. Obslužné rutiny událostí se registrují a konfigurují ve službě prostřednictvím portálu nebo Azure CLI. Když se aktivuje událost klienta, může služba identifikovat, jestli se má událost zpracovat nebo ne. Nyní používáme PUSH režim k vyvolání obslužné rutiny události. Obslužná rutina události na straně serveru zveřejňuje koncový bod, ke kterému má služba veřejně přístup, aby ho vyvolala při aktivaci události. Funguje jako webhook.

Služba Web PubSub doručuje události klienta do upstreamového webhooku pomocí protokolu HTTP CloudEvents.

Pro každou událost služba formuluje požadavek HTTP POST na zaregistrovaný upstream a očekává odpověď HTTP.

Data odesílaná ze služby na server jsou vždy ve formátu CloudEvents binary .

Upstream a validace

Obslužné rutiny událostí musí být zaregistrované a nakonfigurované ve službě prostřednictvím portálu nebo Azure CLI před prvním použitím. Když se aktivuje událost klienta, může služba zjistit, jestli se událost musí zpracovat, nebo ne. Ve verzi Public Preview používáme PUSH režim k vyvolání obslužné rutiny události. Obslužná rutina události na straně serveru zveřejňuje přístupný koncový bod, který služba může vyvolat, když je událost spuštěna. Funguje jako webhook upstream.

Adresa URL může využít parametr {event} k definování šablony adresy URL pro zpracovatele webhooků. Služba vypočítá hodnotu adresy URL webhooku dynamicky, když přijde požadavek klienta. Například když přijde požadavek /client/hubs/chat s nakonfigurovaným vzorem adresy URL http://host.com/api/{event} pro obslužnou rutinu události v centru chat, klient při připojení nejprve odešle POST na tuto adresu URL: http://host.com/api/connect. Toto chování může být užitečné, když klient PubSub WebSocket odesílá vlastní události, které obslužná rutina události pomáhá odesílat různé události do jiného upstreamu. Parametr {event} není povolený v názvu domény adresy URL.

Při nastavování upstreamové obslužné rutiny události prostřednictvím webu Azure Portal nebo rozhraní příkazového řádku se služba řídí ochranou před zneužitím CloudEvents k ověření upstreamového webhooku. Hlavička WebHook-Request-Origin požadavku je nastavená na název xxx.webpubsub.azure.comdomény služby a očekává, že hlavička WebHook-Allowed-Origin odpovědi bude obsahovat tento název domény.

Při ověřování {event} se parametr vyhodnotí na validate. Například při pokusu o nastavení adresy URL na hodnotu http://host.com/api/{event} se služba pokusí vytvořit požadavek typu OPTIONS na http://host.com/api/validate a pouze pokud je odpověď platná, může být konfigurace úspěšně nastavena.

Prozatím nepodporujeme funkci WebHook-Request-Rate a WebHook-Request-Callback.

Ověřování/autorizace mezi službou a webhookem

Pokud chcete vytvořit zabezpečené ověřování a autorizaci mezi vaší službou a webhookem, zvažte následující možnosti a kroky:

• Anonymní režim
• Jednoduché ověřování je poskytováno prostřednictvím nakonfigurované adresy URL Webhooku.
• Použijte autorizaci Microsoft Entra. Další informace najdete v tématu použití spravované identity pro podrobnosti.

1. Povolte identitu pro službu Web PubSub.
2. Vyberte si z existující aplikace Microsoft Entra, která je zkratkou pro webhook.

Správce připojení

Server je ze své podstaty autorizovaným uživatelem. S pomocí role obslužné rutiny událostí server zná metadata klientů, například connectionId a userId, a může:

• Zavření připojení klienta
• Odesílání zpráv klientovi
• Odesílání zpráv klientům, kteří patří stejnému uživateli
• Přidání klienta do skupiny
• Přidání klientů ověřených jako stejný uživatel do skupiny
• Odebrání klienta ze skupiny
• Odstraňte klienty ověřené jako stejný uživatel ze skupiny
• Publikování zpráv do skupiny

Může také udělit nebo odvolat oprávnění k publikování nebo připojení pro klienta PubSub:

• Udělení oprávnění k publikování nebo připojení k určité skupině nebo všem skupinám
• Odvolání oprávnění k publikování nebo připojení pro určitou skupinu nebo pro všechny skupiny
• Zkontrolujte, jestli má klient oprávnění připojit se k určité skupině nebo publikovat do určité skupiny nebo do všech skupin.

Služba poskytuje rozhraní REST API pro server pro správu připojení.

Tady je definovaný podrobný protokol REST API.

Posluchač událostí

Poznámka:

Funkce naslouchání událostem je v předběžné verzi.

Posluchač událostí naslouchá příchozím událostem klienta. Každý posluchač událostí obsahuje filtr, který určuje, jaké druhy událostí jej zajímají, a koncový bod, kam se mají události odesílat.

V současné době podporujeme službu Event Hubs jako koncový bod naslouchacího procesu událostí.

Potřebujete předem zaregistrovat nasluchače událostí, aby služba mohla při vyvolání události klienta předat událost odpovídajícím nasluchačům událostí. Podívejte se na tento dokument pro informace o tom, jak nakonfigurovat naslouchací proces s koncovým bodem Event Hubu.

Můžete nakonfigurovat více posluchačů událostí. Pořadí, ve kterém je nakonfigurujete, nemá vliv na jejich funkce. Pokud událost odpovídá více naslouchacím procesům, událost se odešle všem odpovídajícím naslouchacím procesům. Příklad najdete v následujícím diagramu. Pokud například nakonfigurujete čtyři posluchače událostí současně, každý posluchač, který obdrží shodu, zpracuje událost. Událost klienta, která odpovídá třem z těchto naslouchacích procesů, se odešle třem naslouchacím procesům, přičemž zbývající naslouchací proces bude ignorován.

Obslužnou rutinu události a nasluchače událostí můžete kombinovat na stejnou událost. V tomto případě obdrží událost jak obsluha události, tak nasluchače událostí.

Služba Web PubSub doručuje události klienta do nasloucháčů událostí pomocí rozšíření CloudEvents AMQP pro Azure Web PubSub.

Shrnutí

Role obslužné rutiny událostí zpracovává komunikaci ze služby na server, zatímco role správce zpracovává komunikaci ze serveru do služby. Po sloučení těchto dvou rolí vypadá tok dat mezi službou a serverem podobně jako v následujícím diagramu pomocí protokolu HTTP.

Další kroky

Pomocí těchto prostředků můžete začít vytvářet vlastní aplikaci:

Kurz: Publikování a přihlášení k odběru zpráv ve službě Azure Web PubSub

Kurz: Vytvoření jednoduché chatovací místnosti pomocí azure Web PubSub

Kurz: Použití subprotokolu podporované služby pro streamování klientů

Kurz: Vytváření bezserverového chatu se službou Azure Functions a web pubSub

Návod: Konfigurace naslouchání událostí

Přehrávání s živými ukázkami

Prozkoumání dalších ukázek Azure Web PubSub