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 mohou být napsáni v libovolném jazyce, který má podporu protokolu Websocket.
• Textové i binární zprávy se podporují v rámci jednoho připojení.
• Jednoduchý protokol umožňuje klientům publikovat masáže přímo na sebe.
• Služba spravuje připojení WebSocket za vás.

Termíny

• 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í používající 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 více po sobě jdoucí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 připojení klienta připojí, připojí se k centru a během jeho životnosti patří do tohoto centra. Jakmile se připojení klienta k centru připojí, centrum existuje. 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čů, centrum využívá oproti skupině větší zatížení služby. 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 se podobá skupině "session", relace skupiny se vytvoří, jakmile se někdo připojí ke skupině, a relace zmizí, když nikdo není ve skupině. 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 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: 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 části obslužné rutiny 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 Naslouchací proces 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 .

Workflow

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. Předávat všechny rámce Protokolu WebSocket na nakonfigurovaný upstream (server). Připojení WebSocket se může připojit k libovolnému vlastnímu podprotokolu pro server, který bude zpracovávat, nebo se může připojit s podprotocolem json.webpubsub.azure.v1podporovaným službou, což umožňuje klientům provádět pub/sub přímo. 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

Připojení klienta se připojí ke koncovému /client bodu služby pomocí protokolu WebSocket. 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 naznačuje pojmenování, je jednoduché připojení 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 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 služba vyvolá obslužnou rutinu connected události. 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 naslouchacím procesům událostí( pokud existuje).
3. Když klient odesílá zprávy, služba aktivuje message událost obslužné rutině události. 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í neskuteč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 souvisejícím naslouchacím procesům událostí( pokud existuje).

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 aplikují existující dílčí souhrny .

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

PubSub WebSocket Subprotocol obsahuje podrobnosti json.webpubsub.azure.v1 o subprotocolu.

Všimli jste si, že pro jednoduchého klienta WebSocket je server musí mít roli pro příjem message událostí od klientů. Jednoduché připojení WebSocket vždy aktivuje message událost, když odesílá zprávy, a vždy spoléhá na serverovou stranu ke zpracování zpráv a provádění dalších operací. S pomocí json.webpubsub.azure.v1 subprotocolu 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 publikováním client1 zpráv, do Group1 kterých client1 se 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 obslužnou rutinu 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ý token 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 ověřuje klienta zadáním userId a roles klient má v odpovědi webhooku nebo odmítnout klienta s 401. Část obslužné rutiny události ji podrobně popisuje.

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

Klient může publikovat do jiných klientů jenom v případech, kdy má oprávnění . S roleklienta určuje počáteční oprávnění, která má klient:

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. Naslouchací proces událostí

Obslužná rutina události

Obslužná rutina události zpracovává 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 veřejně přístupný koncový bod pro službu, který se má vyvolat 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 validation

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 veřejně přístupný koncový bod pro službu, která se má vyvolat při aktivaci události. Funguje jako upstream webhooku.

Adresa URL může použít {event} parametr k definování šablony adresy URL pro obslužnou rutinu webhooku. 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 http://host.com/api/{event} adresy URL obslužné rutiny události pro centrum chat, když se klient připojí, nejprve 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 přeloží na validate. Například při pokusu o nastavení adresy URL http://host.com/api/{event}na službu se služba pokusí o možnosti požadavku http://host.com/api/validate a pouze v případě, že odpověď je 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í, které code 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álosti server zná metadata klientů, například, connectionId a userId, aby mohl:

• 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
• Odebrání klientů ověřených 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.

Naslouchací proces událostí

Naslouchací proces události naslouchá příchozím událostem klienta. Každý naslouchací proces událostí obsahuje filtr, který určuje, jaké druhy událostí se týká, koncový bod o tom, 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 naslouchací procesy událostí, aby služba při aktivaci události klienta nasdílel událost odpovídajícím naslouchacím procesům událostí. V tomto dokumentu se dozvíte, jak nakonfigurovat naslouchací proces událostí s koncovým bodem centra událostí.

Můžete nakonfigurovat více naslouchacích procesů 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 naslouchací procesy událostí současně, každý naslouchací proces přijme 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 naslouchací procesy událostí můžete kombinovat pro stejnou událost. V tomto případě události obdrží obslužná rutina události i naslouchací procesy událostí.

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

Shrnutí

Role obslužné rutiny události 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: