Megosztás a következőn keresztül:

Web PubSub ügyfélkódtár JavaScripthez

  • Cikk

Az Azure Web PubSub egy felhőalapú szolgáltatás, amellyel a fejlesztők egyszerűen valós idejű funkciókat hozhatnak létre webalkalmazásokban közzétételi-feliratkozási mintákkal nagy méretekben.

Minden olyan forgatókönyv, amely valós idejű üzenetküldést igényel a kiszolgáló és az ügyfelek között, vagy az ügyfelek között közzétételi-feliratkozási mintákat követve, előnyös lehet a Web PubSub használata. A fejlesztőknek többé nem kell lekérdezni a kiszolgálót úgy, hogy időközönként ismétlődő HTTP-kéréseket küldenek, ami pazarló és nehezen méretezhető.

Az alábbi ábrán látható módon az ügyfelek WebSocket-kapcsolatokat létesítenek a Web PubSub-erőforrással. Ez az ügyfélkódtár:

  • leegyszerűsíti az ügyfélkapcsolatok kezelését
  • leegyszerűsíti az üzenetek küldését az ügyfelek között
  • automatikus újrapróbálkozás az ügyfélkapcsolat nem szándékos megszakadása után
  • megbízhatóan kézbesíti az üzeneteket számban és sorrendben a kapcsolat megszakadása után

Túlcsordulás

Az itt használt kifejezések részleteit a fő fogalmak szakasz ismerteti.

Ez a kódtár az NPM-en található.

Első lépések

Jelenleg támogatott környezetek

Előfeltételek

1. A csomag telepítése @azure/web-pubsub-client

npm install @azure/web-pubsub-client

2. Csatlakozás a Web PubSub-erőforráshoz

Az ügyfél ügyfél-hozzáférési URL-címet használ a szolgáltatáshoz való csatlakozáshoz és hitelesítéshez, amely a következő mintát wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>követi: . Az ügyfél többféleképpen is beszerezheti az ügyfélelérési URL-címet. Ebben a rövid útmutatóban az alábbiakban látható azure portalról másolhat és illeszthet be egyet. (Éles környezetben az ügyfelek általában az ügyfélelérési URL-címet kapják meg az alkalmazáskiszolgálón. Lásd alább a részleteket )

get_client_url

Ahogy a fenti ábrán látható, az ügyfél jogosult üzeneteket küldeni és csatlakozni egy "group1" nevű csoporthoz.

// Imports the client libray
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. Csatlakozás csoportokhoz

Vegye figyelembe, hogy az ügyfél csak azoktól a csoportoktól fogadhat üzeneteket, amelyekhez csatlakozott, és visszahívást kell hozzáadnia az üzenetek fogadásának logikájának megadásához.

// ...continues the code snippet from above

// Specifies the group to join
let groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. Üzenetek küldése csoportnak

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

Példák

Visszahívások hozzáadása csatlakoztatott, leválasztott és leállított eseményekhez

  1. Ha egy ügyfél sikeresen csatlakozik a Web PubSub-erőforráshoz, az connected esemény aktiválódik.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Ha egy ügyfél kapcsolata megszakad, és nem sikerül helyreállítani a kapcsolatot, az disconnected esemény aktiválódik.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. Az stopped esemény akkor aktiválódik, ha az ügyfél kapcsolata megszakad, és az ügyfél nem próbál újracsatlakozni. Ez általában akkor fordul elő, ha a client.stop() rendszer meghívja vagy letiltja, autoReconnect vagy elérte az újracsatlakozási kísérlet megadott korlátját. Ha újra szeretné indítani az ügyfelet, meghívhatja client.start() a leállított eseményt.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Ügyfélelérési URL-cím programozott módon történő létrehozása egyeztetési kiszolgáló használatával

Éles környezetben az ügyfelek általában lekérik az ügyfélelérési URL-címet egy alkalmazáskiszolgálóról. A kiszolgáló a web PubSub-erőforráshoz tartozó kapcsolati karakterlánc tárolja, és létrehozza az ügyfélelérési URL-címet a kiszolgálókódtár @azure/web-pubsubsegítségével.

1. Alkalmazáskiszolgáló

Az alábbi kódrészlet egy példa arra, hogy egy alkalmazáskiszolgáló elérhetővé tesz egy /negotiate elérési utat, és visszaadja az ügyfélelérési URL-címet.

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  let token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. Ügyféloldal

Az alábbi kódrészlet az ügyféloldalra mutat példát.

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    let value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

A minta teljes kódjának megtekintéséhez tekintse meg a samples-browser webhelyet.

Az ügyfél üzeneteket használ fel az alkalmazáskiszolgálóról vagy a csatlakoztatott csoportokból

Az ügyfél visszahívásokat adhat hozzá az alkalmazáskiszolgáló vagy -csoportok üzeneteinek felhasználásához. Felhívjuk a figyelmét arra az group-message esetre, ha az ügyfél csak olyan csoportos üzeneteket fogadhat, amelyekhez csatlakozott.

// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

Újracsatlakozás sikertelenségének kezelése

Ha egy ügyfél kapcsolata megszakad, és nem áll helyre, az összes csoportkörnyezet törlődik a Web PubSub-erőforrásban. Ez azt jelenti, hogy amikor az ügyfél újra csatlakozik, újra csatlakoznia kell a csoportokhoz. Alapértelmezés szerint az ügyfélen engedélyezve van a autoRejoinGroup beállítás.

Azonban tisztában kell lennie a autoRejoinGroupkorlátozásokkal.

  • Az ügyfél csak olyan csoportokat tud újracsatlakozni, amelyekhez eredetileg az ügyfélkód csatlakozott , a kiszolgálóoldali kód nem.
  • Az "újracsatlakozási csoport" műveletek különböző okokból meghiúsulhatnak, például az ügyfél nem rendelkezik engedéllyel a csoportokhoz való csatlakozáshoz. Ilyen esetekben visszahívást kell hozzáadnia a hiba kezeléséhez.
// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

Művelet és újrapróbálkozás

Alapértelmezés szerint a , , client.sendToGroup()client.sendEvent() művelet client.joinGroup()client.leaveGroup()három újrapróbálkozással rendelkezik. A konfigurálást a következőn keresztül végezheti messageRetryOptionsel: . Ha az összes újrapróbálkozás meghiúsult, a rendszer hibát jelez. Az újrapróbálkozást a korábbi újrapróbálkozásokéval megegyező ackId módon végezheti el, hogy a Web PubSub szolgáltatás deduplikálja a műveletet.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

Alprotocol megadása

Módosíthatja az alprotocolt, hogy az ügyfél használhassa. Alapértelmezés szerint az ügyfél a következőt használja json.reliable.webpubsub.azure.v1: . Választhatja a vagy json.webpubsub.azure.v1a használatátjson.reliable.webpubsub.azure.v1.

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonProtocol() });

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonReliableProtocol() });

Fő fogalmak

Kapcsolat

A kapcsolat( más néven ügyfél- vagy ügyfélkapcsolat) a Web PubSubhoz csatlakoztatott egyéni WebSocket-kapcsolatot jelöli. Sikeres csatlakozás esetén a Web PubSub egyedi kapcsolatazonosítót rendel ehhez a kapcsolathoz. Mindegyik WebPubSubClient létrehozza a saját kizárólagos kapcsolatát.

Helyreállítási

Ha egy megbízható protokollt használó ügyfél megszakad, egy új WebSocket megpróbálja létrehozni az elveszett kapcsolat kapcsolatazonosítóját. Ha az új WebSocket-kapcsolat sikeresen csatlakozik, a kapcsolat helyreáll. Az ügyfél leválasztásakor a szolgáltatás megőrzi az ügyfél környezetét, valamint az összes olyan üzenetet, amelyre az ügyfél előfizetett, és amikor az ügyfél helyreáll, a szolgáltatás elküldi ezeket az üzeneteket az ügyfélnek. Ha a szolgáltatás WebSocket hibakódot 1008 ad vissza, vagy a helyreállítási kísérlet több mint 30 másodpercig tart, a helyreállítás sikertelen lesz.

Újracsatlakozás

Az újracsatlakozás akkor történik, ha az ügyfélkapcsolat megszakad, és nem áll helyre. Az újracsatlakozás új kapcsolatot indít el, és az új kapcsolat új kapcsolatazonosítóval rendelkezik. A helyreállítással ellentétben a szolgáltatás az újracsatlakoztatott ügyfelet új ügyfélkapcsolatként kezeli. Az ügyfélkapcsolatnak újra csatlakoznia kell a csoportokhoz. Alapértelmezés szerint az ügyfélkódtár újracsatlakozik a csoportokhoz az újracsatlakozás után.

Hub

A központ egy logikai fogalom az ügyfélkapcsolatok halmazához. Általában egy központot használ egy célra, például egy csevegőközpontot vagy egy értesítési központot. Az ügyfélkapcsolat létrehozásakor csatlakozik egy központhoz, és annak élettartama alatt az adott központhoz tartozik. A különböző alkalmazások különböző központnevek használatával oszthatnak meg egy Web PubSub-t.

Group

A csoport a központtal létesített kapcsolatok részhalmaza. Bármikor hozzáadhat ü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ő. Az ügyfelek több csoporthoz is csatlakozhatnak, és egy csoport több ügyfelet is tartalmazhat.

Felhasználó

Connections a Web PubSub egy felhasználóhoz tartozhat. A felhasználók több kapcsolattal is rendelkezhetnek, például ha egyetlen felhasználó több eszközön vagy több böngészőlapon csatlakozik.

Ügyfélélettartam

A Web PubSub-ügyfelek mindegyike biztonságosan gyorsítótárazható, és egyetlentonként használható az alkalmazás teljes élettartama alatt. A regisztrált eseményvisszahívások ugyanazt az élettartamot osztják meg az ügyféllel. Ez azt jelenti, hogy bármikor hozzáadhat vagy eltávolíthat visszahívásokat, és a regisztrációs állapot nem változik az újracsatlakozás vagy az ügyfél leállítása után.

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, először egy kötegelőt kell használnia. Ennek részleteiért tekintse meg a csomagküldő dokumentációt.

Hibaelhárítás

  • Naplók engedélyezése

    A kódtár használatakor a következő környezeti változót állíthatja be a hibakeresési naplók lekéréséhez.

export AZURE_LOG_LEVEL=verbose

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációt.

További források

Közreműködés

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód összeállításáról és teszteléséről.