Az Azure Web PubSub szolgáltatás belső elemei

Az Azure Web PubSub Service egyszerű WebSocket-kapcsolatokkal egyszerűen közzéteheti/előfizetheti az üzeneteket .

• Az ügyfelek bármilyen, WebSocket-támogatással támogatott nyelven írhatók.
• A szöveges és a bináris üzenetek is támogatottak egy kapcsolaton belül.
• Az egyszerű protokoll lehetővé teszi, hogy az ügyfelek közvetlenül egymásnak tegyenek közzé masszázsokat.
• A szolgáltatás kezeli a WebSocket-kapcsolatokat.

Feltételek

• Szolgáltatás: Azure Web PubSub Service.

• Kapcsolat: Egy kapcsolat, más néven ügyfél- vagy ügyfélkapcsolat, logikai kapcsolat az ügyfél és a Web PubSub szolgáltatás között. Egy "kapcsolaton" keresztül az ügyfél és a szolgáltatás állapotalapú interakciók sorozatát végzi. A különböző protokollokat használó kapcsolatok eltérően viselkedhetnek, például egyes kapcsolatok a hálózati kapcsolat időtartamára korlátozódnak, míg mások az ügyfél és a szolgáltatás közötti több egymást követő hálózati kapcsolatra is kiterjedhetnek.

• Központ: A központ egy logikai fogalom az ügyfélkapcsolatok halmazához. Általában egy hubot használ egy forgatókönyvhöz, például egy csevegőközponthoz vagy egy értesítési központhoz. Amikor egy ügyfélkapcsolat csatlakozik, egy központhoz csatlakozik, és annak élettartama alatt az adott központhoz tartozik. Ha egy ügyfélkapcsolat csatlakozik a központhoz, a központ létezik. A különböző alkalmazások különböző központnevek használatával oszthatnak meg egy Azure Web PubSub szolgáltatást. Bár a hubok száma nincs szigorúan korlátozva, a hubok több szolgáltatásterhelést használnak fel, mint egy csoport. Javasoljuk, hogy a dinamikus generálás helyett egy előre meghatározott központkészlettel rendelkezzen.

• Csoport: A csoport a központhoz való kapcsolatok részhalmaza. Hozzáadhat egy ügyfélkapcsolatot egy csoporthoz, vagy bármikor eltávolíthatja az ügyfélkapcsolatot a csoportból. Ha például egy ügyfél csatlakozik egy csevegőszobához, vagy amikor egy ügyfél elhagyja a csevegőszobát, ez a csevegőszoba csoportnak tekinthető. Egy ügyfél több csoporthoz is csatlakozhat, egy csoport pedig több ügyfelet is tartalmazhat. A csoport olyan, mint egy csoport "munkamenete", a csoportmunkamenet akkor jön létre, ha valaki csatlakozik a csoporthoz, és a munkamenet akkor szűnik meg, amikor senki sem szerepel a csoportban. A csoportnak küldött üzeneteket a rendszer a csoporthoz csatlakoztatott összes ügyfélnek kézbesíti.

• Felhasználó: A Web PubSub-kapcsolatok egy felhasználóhoz tartozhatnak. Egy felhasználó több kapcsolattal is rendelkezhet, például ha egy felhasználó több eszközön vagy több böngészőlapon csatlakozik.

• Üzenet: Amikor az ügyfél csatlakoztatva van, üzeneteket küldhet a felsőbb rétegbeli alkalmazásnak, vagy üzeneteket fogadhat a felsőbb rétegbeli alkalmazásból a WebSocket-kapcsolaton keresztül. Az üzenetek lehetnek egyszerű szöveges, bináris vagy JSON formátumúak, és legfeljebb 1 MB méretűek lehetnek.

• Ügyfélesemények: Az események az ügyfélkapcsolat életciklusa során jönnek létre. Egy egyszerű WebSocket-ügyfélkapcsolat például egy connect eseményt hoz létre, amikor megpróbál csatlakozni a szolgáltatáshoz, egy connected eseményt, amikor sikeresen csatlakozik a szolgáltatáshoz, egy message eseményt, amikor az alapértelmezett módban sendEvent küld üzeneteket a szolgáltatásnak, és egy disconnected eseményt, amikor lecsatlakozik a szolgáltatásról. Az ügyfélesemények részleteit az Ügyfélprotokoll szakasz szemlélteti.

• Eseménykezelő: Az eseménykezelő tartalmazza az ügyfélesemények kezelésére használható logikát. Regisztrálja és konfigurálja az eseménykezelőket a szolgáltatásban a portálon vagy az Azure CLI-ben. A részleteket az Eseménykezelő szakaszban ismertetjük .

• Eseményfigyelő (előzetes verzió): Az eseményfigyelő csak az ügyféleseményeket figyeli, de a válaszukkal nem zavarhatja az ügyfelek élettartamát. A részleteket az Eseményfigyelő szakaszban ismertetjük.

• Kiszolgáló: A kiszolgáló képes kezelni az ügyféleseményeket, kezelni az ügyfélkapcsolatokat, vagy üzeneteket közzétenni a csoportokban. Az eseménykezelő és az eseményfigyelő egyaránt kiszolgálóoldalinak minősül. A kiszolgálóval kapcsolatos részleteket a Kiszolgáló protokoll szakasz ismerteti.

Munkafolyamat

Munkafolyamat a fenti grafikonon látható módon:

1. Az ügyfél a WebSocket-átvitel használatával csatlakozik a szolgáltatásvégponthoz /client . A Szolgáltatás alapértelmezés szerint minden WebSocket-keretet a konfigurált felsőbb rétegbe (kiszolgálóra) továbbítja, a WebSocket-kapcsolat bármilyen egyéni alprotocolhoz csatlakozhat a kiszolgáló számára. Másik lehetőségként az ügyfél csatlakozhat a módhoz sendToGroup , és minden WebSocket-keretet elküldhet egy adott csoportnak. Az ügyfél kapcsolódhat a szolgáltatás által támogatott alprojektekhez is, amelyek olyan funkciókat kínálnak, mint például események küldése a felsőbb rétegbe, csoportok összekapcsolása és üzenetek közvetlen küldése csoportoknak. A részleteket az ügyfélprotokoll ismerteti.
2. Különböző ügyféleseményeken a szolgáltatás a CloudEvents protokoll használatával hívja meg a kiszolgálót. A CloudEvents a Cloud Native Computing Foundation (CNCF) által üzemeltetett események struktúrájának és metaadatainak szabványosított és protokollalapú definíciója. A CloudEvents protokoll részletes implementálása a kiszolgálói szerepkörre támaszkodik, amelyet a kiszolgálóprotokoll ír le.
3. A Web PubSub-kiszolgáló meghívhatja a szolgáltatást a REST API használatával, hogy üzeneteket küldjön az ügyfeleknek vagy kezelje a csatlakoztatott ügyfeleket. A részleteket a kiszolgálóprotokoll ismerteti

Ügyfélprotokoll

Egy ügyfélkapcsolat a szolgáltatás végpontjára csatlakozik /client a WebSocket protokoll használatával. A WebSocket protokoll teljes kétirányú kommunikációs csatornákat biztosít egyetlen TCP-kapcsolaton keresztül, és az IETF 2011-ben RFC 6455-ként szabványosította. A legtöbb nyelv natív támogatást nyújt a WebSocket-kapcsolatok elindításához.

Szolgáltatásunk kétféle ügyfelet támogat:

• Az egyik az egyszerű WebSocket-ügyfél
• A másik neve PubSub WebSocket-ügyfél

Az egyszerű WebSocket-ügyfél

Az egyszerű WebSocket-ügyfél, ahogy az elnevezés is mutatja, egy egyszerű WebSocket-kapcsolat. Egyéni alprotocolja is lehet.

A JS-ben például egy egyszerű WebSocket-ügyfél az alábbi kóddal hozható létre.

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

Az egyszerű WebSocket-ügyfélnek két módja van. Az alapértelmezett mód sendEvent egy ügyfél-kiszolgáló<> architektúrát követ, ahogy az alábbi szekvenciadiagram is mutatja:

1. Amikor az ügyfél elindít egy WebSocket-kézfogást, a szolgáltatás megpróbálja meghívni a connect WebSocket-kézfogás eseménykezelőt. A fejlesztők ezzel a kezelővel kezelhetik a WebSocket-kézfogást, meghatározhatják a használni kívánt alprotocolt, hitelesíthetik az ügyfelet, és csoportokhoz csatlakoztathatják az ügyfelet.
2. Ha az ügyfél sikeresen csatlakozik, a szolgáltatás meghív egy eseménykezelőt connected . Értesítésként működik, és nem blokkolja az ügyfelet az üzenetek küldésében. A fejlesztők ezzel a kezelővel adattárolást végezhetnek, és üzeneteket küldhetnek az ügyfélnek. A szolgáltatás egy eseményt connected is leküld minden eseményfigyelőnek, ha van ilyen.
3. Amikor az ügyfél üzeneteket küld, a szolgáltatás eseményt message indít el az eseménykezelőnek. Ez az esemény a WebSocket-keretben küldött üzeneteket tartalmazza. A kódnak el kell küldenie az üzeneteket az eseménykezelőben. Ha az eseménykezelő nem sikeres válaszkódot ad vissza, a szolgáltatás megszakad az ügyfélkapcsolattal. A szolgáltatás egy eseményt message is leküld az összes érintett eseményfigyelőnek, ha van ilyen. Ha a szolgáltatás nem talál regisztrált kiszolgálókat az üzenetek fogadásához, a szolgáltatás az ügyfélkapcsolatot is megszakad.
4. Amikor az ügyfél megszakad, a szolgáltatás megpróbálja aktiválni az disconnected eseményt az eseménykezelőnek, miután észleli a leválasztást. A szolgáltatás egy eseményt disconnected is leküld minden eseményfigyelőnek, ha van ilyen.

Forgatókönyvek

Ezek a kapcsolatok egy tipikus ügyfél-kiszolgáló architektúrában használhatók, ahol az ügyfél üzeneteket küld a kiszolgálónak, a kiszolgáló pedig eseménykezelőkkel kezeli a bejövő üzeneteket. Akkor is használható, ha az ügyfelek meglévő alprojekteket alkalmaznak az alkalmazáslogikában.

A PubSub WebSocket-ügyfél

A szolgáltatás egy adott, úgynevezett json.webpubsub.azure.v1alprojektet is támogat, amely lehetővé teszi az ügyfelek számára, hogy közvetlenül tegyenek közzé/iratkozzanak fel a felsőbb rétegbeli kiszolgálóra való oda-vissza utazás helyett. A WebSocket-kapcsolatot egy PubSub WebSocket-ügyfél alprotocoljával json.webpubsub.azure.v1 hívjuk meg. További információkért tekintse meg a Web PubSub ügyfél specifikációját a GitHubon.

A JS-ben például a PubSub WebSocket-ügyfél az alábbi kóddal hozható létre.

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

A PubSub WebSocket-ügyfél a következőt teheti:

• Csatlakozzon egy csoporthoz, például:

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

• Hagyjon el egy csoportot, például:

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

• Üzenetek közzététele egy csoportban, például:

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

• Egyéni események küldése a felsőbb rétegbeli kiszolgálóra, például:

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

A PubSub WebSocket Subprotocol az alprotocol részleteit json.webpubsub.azure.v1 tartalmazza.

Az egyszerű WebSocket-ügyfél félelmetes módjában sendEvent a kiszolgálónak szerepkörrel kell rendelkeznie az message események ügyfelektől való fogadásához. Egy egyszerű WebSocket-kapcsolat sendEvent módban mindig aktivál egy message eseményt, amikor üzeneteket küld, és mindig a kiszolgálóoldalra támaszkodik az üzenetek feldolgozásához és más műveletek végrehajtásához. A sendToGroup mód csak az ügyfelek számára teszi lehetővé, hogy közvetlenül tegyenek közzé üzeneteket a csoportokban anélkül, hogy kéréseket indítanának a kiszolgálóra, ami még mindig korlátozott. json.webpubsub.azure.v1 az alprotocol lehetővé teszi az ügyfelek számára, hogy sokkal többet tegyenek anélkül, hogy kéréseket indítanának a kiszolgálóra. Segítségével egy jogosult ügyfél csatlakozhat egy csoporthoz, és közvetlenül közzéteheti az üzeneteket egy csoportban. Az üzeneteket különböző eseménykezelőkhöz/eseményfigyelőkhöz is irányíthatja az üzenethez tartozó esemény testreszabásával.

Forgatókönyvek

Ezek az ügyfelek akkor használhatók, ha az ügyfelek beszélni szeretnének egymással. A rendszer üzeneteket küld a szolgáltatásnak client2 , és a szolgáltatás közvetlenül client1 kézbesíti az üzenetet, ha az ügyfelek jogosultak erre.

1. ügyfél:

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

Ügyfél2:

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

Ahogy a fenti példa is mutatja, client2 az adatokat közvetlenül az client1 üzenetek Group1client1 közzétételével küldi el.

Ügyfélesemények összegzése

Az ügyfélesemények két kategóriába sorolhatók:

• Szinkron események (blokkolás) A szinkron események blokkolják az ügyfél munkafolyamatát.

  • connect: Ez az esemény csak eseménykezelőre vonatkozik. Amikor az ügyfél elindít egy WebSocket-kézfogást, az esemény aktiválódik, és a fejlesztők eseménykezelővel connect kezelhetik a WebSocket-kézfogást, meghatározhatják a használni kívánt alprotocolt, hitelesíthetik az ügyfelet, és csoportokhoz csatlakoztathatják az ügyfelet.
  • message: Ez az esemény akkor aktiválódik, ha egy ügyfél üzenetet küld.

• Az aszinkron események (nem blokkolók) az aszinkron események nem blokkolják az ügyfél-munkafolyamatot. Ehelyett értesítést küldenek a kiszolgálónak. Ha egy ilyen eseményindító meghiúsul, a szolgáltatás naplózza a hiba részleteit.

  • connected: Ez az esemény akkor aktiválódik, ha egy ügyfél sikeresen csatlakozik a szolgáltatáshoz.
  • disconnected: Ez az esemény akkor aktiválódik, ha egy ügyfél megszakította a kapcsolatot a szolgáltatással.

Ügyfélüzenetek korlátja

Egy WebSocket-keret maximális üzenetmérete 1 MB.

Ügyfél-hitelesítés

Hitelesítési munkafolyamat

Az ügyfél aláírt JWT-jogkivonatot használ a szolgáltatáshoz való csatlakozáshoz. A felsőbb réteg akkor is elutasíthatja az ügyfelet, connect ha a bejövő ügyfél eseménykezelője. Az eseménykezelő hitelesíti az ügyfelet a webhook válaszában szereplő és roleaz ügyfél által kapott adatok megadásávaluserId, vagy az ügyfél elutasításával a 401-es számmal. Az eseménykezelő szakasz részletesen leírja.

Az alábbi grafikon a munkafolyamatot ismerteti.

Az ügyfél csak akkor tehet közzé közzétételt más ügyfeleken, ha arra jogosult . Az roleügyfél s-jei határozzák meg az ügyfél kezdeti engedélyeit:

A kiszolgálóoldal dinamikusan adhat vagy vonhat vissza engedélyeket az ügyfél számára a kiszolgálóprotokollon keresztül, amint azt egy későbbi szakaszban bemutatjuk.

Kiszolgálóprotokoll

A kiszolgálóprotokoll biztosítja a kiszolgáló funkcióit az ügyfélesemények kezeléséhez, valamint az ügyfélkapcsolatok és a csoportok kezeléséhez.

A kiszolgálóprotokoll általában három szerepkört tartalmaz:

1. Eseménykezelő
2. Kapcsolatkezelő
3. Eseményfigyelő

Eseménykezelő

Az eseménykezelő kezeli a bejövő ügyféleseményeket. Az eseménykezelők a portálon vagy az Azure CLI-ben vannak regisztrálva és konfigurálva a szolgáltatásban. Egy ügyfélesemény aktiválásakor a szolgáltatás azonosíthatja, hogy az eseményt kezelni kell-e vagy sem. Most mód használatával PUSH hívjuk meg az eseménykezelőt. A kiszolgálóoldali eseménykezelő nyilvánosan elérhető végpontot tesz elérhetővé a szolgáltatás számára, amely meghívható az esemény aktiválásakor. Webhookként működik.

A Web PubSub szolgáltatás a CloudEvents HTTP protokollal biztosítja az ügyféleseményeket a felsőbb rétegbeli webhooknak.

A szolgáltatás minden eseményhez HTTP POST-kérést fogalmaz meg a regisztrált upstream felé, és HTTP-választ vár.

A szolgáltatásból a kiszolgálóra küldött adatok mindig CloudEvents formátumúak binary .

Felsőbb rétegbeli és érvényesítési

Az eseménykezelőket az első használat előtt regisztrálni kell és konfigurálni kell a szolgáltatásban a portálon vagy az Azure CLI-ben. Egy ügyfélesemény aktiválásakor a szolgáltatás azonosíthatja, hogy az eseményt kezelni kell-e vagy sem. A nyilvános előzetes verzióhoz az eseménykezelő meghívására szolgáló módot használjuk PUSH . A kiszolgálóoldali eseménykezelő nyilvánosan elérhető végpontot tesz elérhetővé a szolgáltatás számára, amely meghívható az esemény aktiválásakor. Ez egy webhookként működik a felsőbb rétegben.

Az URL-cím paraméterrel {event} definiálhat EGY URL-sablont a webhookkezelőhöz. A szolgáltatás dinamikusan kiszámítja a webhook URL-címét az ügyfélkérés érkezésekor. Ha például egy kérés /client/hubs/chat érkezik, egy konfigurált eseménykezelő URL-mintával http://host.com/api/{event} a központhoz chat, amikor az ügyfél csatlakozik, először postázni fogja ezt az URL-címet: http://host.com/api/connect. Ez a viselkedés akkor lehet hasznos, ha egy PubSub WebSocket-ügyfél egyéni eseményeket küld, és az eseménykezelő segít különböző eseményeket különböző eseményeket küldeni a különböző felsőbb rétegbe. A {event} paraméter nem engedélyezett az URL-tartománynévben.

Amikor az eseménykezelőt az Azure Portalon vagy a PARANCSSOR-on keresztül állítja be, a szolgáltatás a CloudEvents visszaélés elleni védelmét követi a felsőbb rétegbeli webhook ellenőrzéséhez. A WebHook-Request-Origin kérelem fejléce a szolgáltatástartomány nevére xxx.webpubsub.azure.comvan állítva, és arra számít, hogy a válasz fejléce WebHook-Allowed-Origin tartalmazza ezt a tartománynevet.

Az ellenőrzés során a {event} paraméter a következőre validatelesz feloldva: . Ha például az URL-címet http://host.com/api/{event}szeretné beállítani, a szolgáltatás megpróbálja BEÁLLÍTANI a kérésthttp://host.com/api/validate, és csak akkor, ha a válasz érvényes, a konfiguráció sikeresen beállítható.

Egyelőre nem támogatjuk a WebHook-Request-Rate és a WebHook-Request-Callback függvényt.

Hitelesítés/Hitelesítés a szolgáltatás és a webhook között

A szolgáltatás és a webhook közötti biztonságos hitelesítés és engedélyezés létrehozásához vegye figyelembe az alábbi lehetőségeket és lépéseket:

• Névtelen mód
• A konfigurált Webhook URL-címén keresztül biztosított egyszerű hitelesítés code .
• Használja a Microsoft Entra-hitelesítést. További információkért tekintse meg , hogyan használhatja a felügyelt identitást a részletekért.

1. Identitás engedélyezése a Web PubSub szolgáltatáshoz.
2. Válasszon a meglévő Microsoft Entra-alkalmazásból, amely a webhook-webalkalmazást jelöli.

Kapcsolatkezelő

A kiszolgáló természete szerint jogosult felhasználó. Az eseménykezelő szerepkör segítségével a kiszolgáló ismeri például az ügyfelek metaadatait, connectionId és userIdígy a következőt teheti:

• Ügyfélkapcsolat bezárása
• Üzenetek küldése ügyfélnek
• Üzenetek küldése ugyanahhoz a felhasználóhoz tartozó ügyfeleknek
• Ügyfél hozzáadása csoporthoz
• Azonos felhasználóként hitelesített ügyfelek hozzáadása egy csoporthoz
• Ügyfél eltávolítása egy csoportból
• Azonos felhasználóként hitelesített ügyfelek eltávolítása egy csoportból
• Üzenetek közzététele csoporton

Emellett közzétételi/csatlakozási engedélyeket is adhat vagy vonhat vissza a PubSub-ügyfélhez:

• Közzétételi/csatlakozási engedélyek megadása adott csoportnak vagy minden csoportnak
• Közzétételi/csatlakozási engedélyek visszavonása adott csoporthoz vagy az összes csoporthoz
• Ellenőrizze, hogy az ügyfél rendelkezik-e engedéllyel a csatlakozáshoz vagy a közzétételhez egy adott csoporthoz vagy az összes csoporthoz

A szolgáltatás REST API-kat biztosít a kiszolgáló számára a kapcsolatkezeléshez.

Itt definiáljuk a részletes REST API protokollt.

Eseményfigyelő

Az eseményfigyelő figyeli a bejövő ügyféleseményeket. Minden eseményfigyelő tartalmaz egy szűrőt, amely meghatározza, hogy milyen típusú eseményeket érint, és egy végpontot, amely meghatározza, hogy hová küldje az eseményeket.

Jelenleg az Event Hubsot támogatjuk eseményfigyelő végpontként.

Előre regisztrálnia kell az eseményfigyelőket, hogy egy ügyfélesemény aktiválásakor a szolgáltatás le tudja küldeni az eseményt a megfelelő eseményfigyelőknek. Ebből a dokumentumból megtudhatja, hogyan konfigurálhat eseményfigyelőt eseményközpont-végponttal.

Több eseményfigyelőt is konfigurálhat. A konfigurálásuk sorrendje nem befolyásolja a működésüket. Ha egy esemény több figyelőnek felel meg, az eseményt a rendszer az összes egyező figyelőnek küldi el. Egy példaért tekintse meg az alábbi ábrát. Ha például egyszerre négy eseményfigyelőt konfigurál, minden egyezést fogadó figyelő feldolgozza az eseményt. A három figyelővel egyező ügyféleseményt a rendszer három figyelőnek küldi el, a fennmaradó figyelőt pedig figyelmen kívül hagyja.

Egy eseménykezelőt és eseményfigyelőt kombinálhat ugyanahhoz az eseményhez. Ebben az esetben az eseménykezelő és az eseményfigyelő is megkapja az eseményt.

A Web PubSub szolgáltatás ügyféleseményeket biztosít az eseményfigyelőknek az Azure Web PubSub CloudEvents AMQP bővítményével.

Összegzés

Az eseménykezelő szerepkör kezeli a szolgáltatás és a kiszolgáló közötti kommunikációt, míg a kezelői szerepkör kezeli a kiszolgáló és a szolgáltatás közötti kommunikációt. A két szerepkör kombinálása után a szolgáltatás és a kiszolgáló közötti adatfolyam a HTTP protokollt használó alábbi diagramhoz hasonlóan néz ki.

Következő lépések

Használja ezeket az erőforrásokat a saját alkalmazás létrehozásához: