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

Web PubSub ügyfélkódtár JavaScripthez

Azure Web PubSub egy felhőalapú szolgáltatás, amely segít a fejlesztőknek abban, hogy nagy léptékű közzétételi-feliratkozási mintákkal valós idejű funkciókat építsenek ki a webalkalmazásokban.

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, hasznos lehet a Web PubSub használata. A fejlesztőknek már 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 tervezett megszakadása után
  • megbízhatóan kézbesíti az üzeneteket számban és sorrendben a kapcsolat megszakadása utáni helyreállítás után

túlcsordulási

Az itt használt kifejezések részleteit fő fogalmak szakaszban ismertetjük.

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

Kezdetekhez

Jelenleg támogatott környezetek

Előfeltételek

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

npm install @azure/web-pubsub-client

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

Az ügyfél egy ügyfélelérési URL-címet használ a szolgáltatáshoz való csatlakozáshoz és hitelesítéshez, amely a wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>mintáját 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 másolhat és beilleszthet egyet az Azure Portalról, amely alább látható. (É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 az alábbi részleteket )

get_client_url

Ahogy a fenti ábrán látható, az ügyfél jogosult üzeneteket küldeni és csatlakozni egy "csoport1" 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. Csoportok csatlakoztatása

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
const 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, a connected esemény aktiválódik.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Ha egy ügyfél megszakad, és nem sikerül helyreállítani a kapcsolatot, a disconnected esemény aktiválódik.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. A stopped esemény akkor aktiválódik, ha az ügyfél megszakad , és az ügyfél nem próbál újracsatlakozni. Ez általában a client.stop() meghívása után történik, vagy autoReconnect le van tiltva, 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ényben.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Ügyfélelérési URL-cím programozott létrehozása tárgyalá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 sztringet 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 egy alkalmazáskiszolgálóra, amely egy /negotiate elérési utat tesz elérhetővé, é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) => {
  const 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 () => {
    const value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

A minta teljes kódjának megtekintéséhez tekintse meg mintaböngésző.

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 figyelmét, hogy group-message esemény esetén az ügyfél csak fogadhat csoportüzeneteket, 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 leválasztva van, és nem sikerül helyreállítani a helyreállítást, az összes csoportkörnyezet törlődik a Web PubSub-erőforrásban. Ez azt jelenti, hogy amikor az ügyfél újra csatlakozik, újra kell csatlakoznia a csoportokhoz. Alapértelmezés szerint az ügyfél autoRejoinGroup beállítás engedélyezve van.

Azonban tisztában kell lennie autoRejoinGroupkorlátaival.

  • Az ügyfél csak olyan csoportokat tud újracsatlakozni, amelyekhez eredetileg az ügyfélkód csatlakozik, a kiszolgálóoldali kód nem.
  • A "csoport újracsatlakozása" műveletek különböző okok miatt 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 az olyan műveletek, mint a client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() három újrapróbálkozással rendelkezik. A messageRetryOptionskonfigurálható. Ha az összes újrapróbálkozás sikertelen volt, a rendszer hibát jelez. Az újrapróbálkozást a korábbi újrapróbálkozásokéval megegyező ackId továbbíthatja, 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 ügyfél által használandó alprotocolt. Alapértelmezés szerint az ügyfél json.reliable.webpubsub.azure.v1használ. Választhat, hogy json.reliable.webpubsub.azure.v1 vagy json.webpubsub.azure.v1használ.

// 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őbb fogalmak

Kapcsolat

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

Felépülés

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 ad vissza 1008, vagy a helyreállítási kísérlet több mint 30 másodpercig tart, a helyreállítás sikertelen lesz.

Újra

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.

Kerékagy

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. Amikor létrejön egy ügyfélkapcsolat, az egy központhoz csatlakozik, és annak élettartama alatt az adott központhoz tartozik. A különböző alkalmazások különböző hubnevek használatával oszthatnak meg egy Web PubSub-t.

Csoport

A csoport a központhoz való kapcsolatok egy 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.

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.

Ügyfél élettartama

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 élettartama megegyezik 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 módjáról további információt a csomagküldő dokumentációbantalál.

Hibaelhárítás

  • Naplók engedélyezése

    A következő környezeti változóval lekérheti a hibakeresési naplókat a kódtár használatakor.

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óit.

További erőforrások

Hozzájárulá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.

  • Last updated on