Web PubSub ügyféloldali SDK JavaScripthez

Feljegyzés

Az itt használt kifejezések részleteit a fő fogalmakról szóló cikk ismerteti.

Az ügyféloldali SDK célja a fejlesztői munkafolyamat felgyorsítása; pontosabban,

  • 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

Ahogy a diagramon látható, az ügyfelek WebSocket-kapcsolatokat létesítenek a Web PubSub-erőforrással.

Web PubSub-erőforrással létesített WebSocket-kapcsolatot létrehozó ügyfelek képernyőképe

Fontos

A cikkben szereplő nyers kapcsolati sztring csak bemutató célokra jelennek meg.

A kapcsolati sztring tartalmazzák azokat az engedélyezési információkat, amelyekre az alkalmazásnak szüksége van az Azure Web PubSub szolgáltatás eléréséhez. A kapcsolati sztring belüli hozzáférési kulcs hasonló a szolgáltatás gyökérjelszójához. Éles környezetben mindig védje a hozzáférési kulcsokat. Az Azure Key Vault használatával biztonságosan kezelheti és elforgathatja a kulcsokat, és biztonságossá teheti a kapcsolatot.WebPubSubServiceClient

Kerülje a hozzáférési kulcsok más felhasználók számára való terjesztését, a szigorú kódolást, illetve a mások számára hozzáférhető egyszerű szövegek mentését. Ha úgy véli, hogy illetéktelenek lettek, forgassa el a kulcsokat.

Első lépések

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 a szolgáltatáshoz való csatlakozást és hitelesítést használja Client Access URL , 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 beszerezhető Client Access URL. Ebben a rövid útmutatóban az Azure Portalról másolhat és illeszthet be egyet. (Éles környezetben az ügyfelek általában az alkalmazáskiszolgálón jönnek Client Access URL létre. Részletek megtekintése )

Képernyőkép az Ügyfélelérési URL-cím lekéréséről az Azure Portalon

Ahogy a diagramon látható, az ügyfél jogosult üzeneteket küldeni és csatlakozni egy adott nevű csoporthoz group1.

// Imports the client library
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

Az ügyfél csak azoktól a csoportoktól fogadhat üzeneteket, amelyekhez csatlakozott. Visszahívással megadhatja az üzenetek fogadásakor teendők logikáját.

// ...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

Kezelés connectedés disconnectedstopped események

Az Azure Web PubSub olyan rendszereseményeket aktivál, mint a connected. disconnectedstopped Eseménykezelőket regisztrálhat, hogy eldöntse, mit kell tennie a programnak az események aktiválásakor.

  1. Ha egy ügyfél sikeresen csatlakozik a Web PubSub-erőforráshoz, az connected esemény aktiválódik. Ez a kódrészlet egyszerűen kinyomtatja a kapcsolatazonosítót
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, az disconnected esemény aktiválódik. Ez a kódrészlet egyszerűen kinyomtatja az üzenetet.
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 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ényt.
// Registers an event handler for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Alkalmazáskiszolgáló használata programozott módon történő létrehozáshoz Client Access URL

Éles környezetben az ügyfelek általában egy alkalmazáskiszolgálóról kérnek le Client Access URL . A kiszolgáló a connection string Web PubSub erőforrást tárolja, és a kiszolgálóoldali kódtár Client Access URLsegítségével hozza létre azokat@azure/web-pubsub.

1. Alkalmazáskiszolgáló

A kódrészlet egy példa egy alkalmazáskiszolgálóra, amely egy végpontot /negotiate tesz elérhetővé, és visszaadja Client Access URLazt.

A cikkben szereplő nyers kapcsolati sztring csak bemutató célokra jelennek meg. Éles környezetben mindig védje a hozzáférési kulcsokat. Az Azure Key Vault használatával biztonságosan kezelheti és elforgathatja a kulcsokat, és biztonságossá teheti a kapcsolatot.WebPubSubServiceClient

// 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

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();

Feljegyzés

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

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óktól vagy csoportoktól érkező üzenetek felhasználásához.

// Registers a listener for the "server-message". The callback is 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 is 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}`);
});

Feljegyzés

Esemény esetén group-message az ügyfél csak azoktól a csoportoktól fogadhat üzeneteket, amelyekhez csatlakozott.

Ú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. Az ügyfél alapértelmezés szerint engedélyezve van autoRejoinGroup .

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

  • Az ügyfél csak olyan csoportokat tud újracsatlakozni, amelyekhez az ügyfélkód csatlakozott, és nem a kiszolgálóoldali kód.
  • A "Csoport újracsatlakozása" művelet különböző okok miatt meghiúsulhat, 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}`);
})

Ismét

Alapértelmezés szerint az olyan művelet, mint client.joinGroup()a , client.leaveGroup()client.sendToGroup()három client.sendEvent() újrapróbálkozással rendelkezik. Konfigurálható a messageRetryOptions. Ha az összes újrapróbálkozás sikertelen volt, hiba jelenik meg. 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});
}

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, egy kötegelőt kell használnia. A csomagok létrehozásának részleteiért tekintse meg a csomagkötegek dokumentációját.

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.

Élő nyomkövetés

Az Azure Portal élő nyomkövetési eszközével élő üzenetforgalmat vizsgálhat meg a Web PubSub-erőforráson keresztül.

  • Last updated on