Web PubSub klientská knihovna pro JavaScript

Azure Web PubSub je cloudová služba, která pomáhá vývojářům snadno vytvářet funkce v reálném čase ve webových aplikacích s formáty publikování a odběru ve velkém měřítku.

Jakýkoli scénář, který vyžaduje komunikaci v reálném čase mezi serverem a klienty nebo mezi klienty podle vzorců publish-subscribe, může využít použití Web PubSub. Vývojáři už nemusí server dotazovat opakovaným HTTP dotazem v intervalech, což je plýtvání a obtížné škálování.

Jak je znázorněno na diagramu níže, vaši klienti navazují WebSocket spojení s vaším zdrojem Web PubSub. Tato klientská knihovna:

zjednodušuje správu klientských připojení.
zjednodušuje odesílání zpráv mezi klienty.
automaticky znovu připojí po nezamýšlených výpadcích připojení klienta
spolehlivě doručuje zprávy v počtu a pořadí po zotavení z výpadků spojení

Přetečení

Podrobnosti o použitých termínech jsou popsány v sekci klíčových pojmů .

Tato knihovna je hostována na NPM.

Začínáme

Aktuálně podporovaná prostředí

LTS verze Node.js

Předpoklady

1. Instalace `@azure/web-pubsub-client` balíčku

npm install @azure/web-pubsub-client

2. Spojte se se svým zdrojem Web PubSub

Klient používá adresu URL klientského přístupu k připojení a ověření pomocí služby, která se řídí vzorem wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Klient může mít několik způsobů, jak získat adresu URL klientského přístupu. Pro tento rychlý start můžete zkopírovat a vložit jeden z Azure Portalu, který je zobrazen níže. (Pro produkci obvykle klienti získávají URL přístupu klienta generovanou na vašem aplikačním serveru. Podrobnosti viz níže :)

get_client_url

Jak je znázorněno na diagramu výše, klient má oprávnění posílat zprávy a připojit se ke konkrétní skupině nazvané "group1".

import { WebPubSubClient } from "@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();

3. Připojit se ke skupinám

Všimněte si, že klient může přijímat zprávy pouze od skupin, ke kterým se připojil, a je potřeba přidat callback, který určí logiku při přijímání zpráv.

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");

// 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}`);
});

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

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

4. Posílejte zprávy skupině

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";
await client.joinGroup(groupName);

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

5. Vyvolání upstream událostí (náhled)

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const result = await client.invokeEvent("processOrder", { orderId: 1 }, "json");
console.log(`Invocation result: ${JSON.stringify(result.data)}`);

invokeEvent odešle invoke požadavek službě, čeká na korelované invokeResponse, a vrátí užitečné zatížení. Invokaci můžete přerušit tím, že projdete .{ abortSignal } Streamování a invokace iniciované službou zatím nejsou podporovány.

Příklady

Přidejte zpětná volání pro připojené, odpojené a zastavené události

Když je klient úspěšně připojen k vašemu zdroji Web PubSub, událost connected se spustí.

client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});

Když je klient odpojen a nepodaří se mu obnovit spojení, událost disconnected se spustí.

client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});

Událost stopped se spustí, když je klient odpojen a klient přestane zkoušet znovu připojit. To se obvykle stává po zavolání autoReconnect nebo client.stop() deaktivaci nebo dosažení stanoveného limitu pro pokus o opětovné připojení. Pokud chcete klienta restartovat, můžete zavolat client.start() událost zastavení.

// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Použijte vyjednávací server k programovému generování URL přístupu klienta

V produkci klienti obvykle získávají URL přístupu klienta z aplikačního serveru. Server drží spojovací řetězec k vašemu zdroji Web PubSub a generuje URL přístupu klienta s pomocí serverové knihovny @azure/web-pubsub.

1. Aplikační server

Níže uvedený úryvek kódu je příkladem aplikačního serveru, který zpřístupní cestu /negotiate a vrátí URL přístupu klienta.

import express from "express";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
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. Klientská strana

Níže uvedený úryvek kódu je příkladem klientské strany.

import { WebPubSubClient } from "@azure/web-pubsub-client";

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

await client.start();

Pro zobrazení celého kódu tohoto vzorku prosím navštivte samples-browser.

Klient spotřebovává zprávy ze serveru aplikace nebo ze skupin

Klient může přidávat zpětné volání, aby spotřebovával zprávy z vašeho aplikačního serveru nebo skupin. Upozorňujeme, že pro group-message událost může klient přijímat pouze skupinové zprávy, do kterých se připojil.

// 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}`);
});

Řešení selhání opětovného připojení

Když je klient odpojen a nedokáže se obnovit, všechny skupinové kontexty budou vyčištěny ve vašem Web PubSub zdroji. To znamená, že když se klient znovu připojí, musí se znovu připojit ke skupinám. Ve výchozím nastavení má klient autoRejoinGroup možnost zapnutou.

Nicméně byste měli být obeznámeni autoRejoinGroups omezeními tohoto pojištění.

Klient se může znovu připojit pouze ke skupinám, ke kterým byl původně připojen klientský kód, nikoli kód na straně serveru.
Operace "opětovného připojení ke skupině" mohou selhat z různých důvodů, například klient nemá oprávnění ke vstupu do skupin. V takových případech je potřeba přidat callback, aby se s tímto selháním vypořádalo.

import { WebPubSubClient } from "@azure/web-pubsub-client";

// 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}`);
});

Operace a opakování

Ve výchozím nastavení má operace jako client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() tři opakované pokusy. Můžete nastavit pomocí .messageRetryOptions Pokud všechny pokusy selhaly, bude vyhozena chyba. Můžete opakovat pokusy tak, že budete předávat stejné ackId pokusy jako předchozí, aby služba Web PubSub mohla operaci deduplikovat.

import { WebPubSubClient, SendMessageError } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";

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

Specifikujte podprotokol

Můžete změnit podprotokol tak, aby ho klient používal. Ve výchozím nastavení klient používá json.reliable.webpubsub.azure.v1. Můžete si zvolit použití json.reliable.webpubsub.azure.v1 nebo json.webpubsub.azure.v1.

import { WebPubSubClient, WebPubSubJsonProtocol } from "@azure/web-pubsub-client";

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

import { WebPubSubClient, WebPubSubJsonReliableProtocol } from "@azure/web-pubsub-client";

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

Klíčové koncepty

Připojení

Připojení, také známé jako klient nebo klientské připojení, představuje individuální WebSocket připojení připojené k Web PubSub. Po úspěšném připojení je Web PubSub přiřazen unikátní ID připojení. Každý WebPubSubClient vytváří své vlastní exkluzivní spojení.

Recovery

Pokud se klient používající spolehlivé protokoly odpojí, nový WebSocket se pokusí navázat spojení pomocí ID spojení, které ztratilo spojení. Pokud je nové připojení WebSocket úspěšně připojeno, připojení je obnoveno. Po celou dobu, kdy je klient odpojen, služba uchovává kontext klienta i všechny zprávy, na které byl klient přihlášen, a když se klient zotaví, služba tyto zprávy klientovi odešle. Pokud služba vrátí chybový kód 1008 WebSocket nebo pokus o obnovení trvá déle než 30 sekund, obnova selže.

Reconnect

K opětovnému připojení dochází, když klientské připojení přestane fungovat a nepodaří se ho obnovit. Opětovné připojení spustí nové spojení a nové spojení má nové ID připojení. Na rozdíl od obnovy služba považuje znovu připojeného klienta za nové klientské připojení. Klientské připojení se musí znovu připojit ke skupinám. Ve výchozím nastavení se klientská knihovna po opětovném připojení znovu připojuje ke skupinám.

Centrum

Hub je logický koncept pro sadu klientských spojení. Obvykle používáte jeden hub pro jeden účel, například chatovací hub nebo notifikační hub. Když je klientské připojení vytvořeno, připojí se k hubu a během svého života do něj patří. Různé aplikace mohou sdílet jeden Web PubSub pomocí různých názvů hubů.

Skupina

Skupina je podmnožina spojení s hubem. Můžete kdykoli přidat klientské připojení ke skupině, nebo ho ze skupiny odstranit. Například když klient vstoupí do chatovací místnosti, nebo když klient opustí chatovací místnost, lze tuto místnost považovat za skupinu. Klient se může připojit k více skupinám a skupina může obsahovat více klientů.

User

Připojení k Web PubSub může patřit jednomu uživateli. Uživatel může mít více připojení, například když je jeden uživatel připojen napříč více zařízeními nebo více kartami prohlížeče.

Doživotní klient

Každý z klientů Web PubSub je bezpečný ke cachování a používání jako singleton po celou dobu existence aplikace. Registrované callbacky událostí mají stejnou životnost s klientem. To znamená, že můžete kdykoli přidávat nebo odebírat callbacky a stav registrace se po opětovném připojení nebo zastavení klienta nezmění (callback).

JavaScriptový balíček

Pro použití této klientské knihovny v prohlížeči je nejprve potřeba použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

Troubleshooting

Povolení protokolů

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků HTTP a odpovědí, nastavte proměnnou AZURE_LOG_LEVEL prostředí na infohodnotu .

export AZURE_LOG_LEVEL=verbose

Případně můžete protokolování povolit za běhu voláním setLogLevel příkazu @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Živé trasování

Použijte nástroj Live Trace z portálu Web PubSub pro zobrazení živého provozu.

Dodatečné zdroje

Zjistěte více o oprávněních klientů, viz oprávnění
Server SDK - JavaScriptová dokumentace
Dokumentace produktu
Ukázky

Contributing

Pokud chcete přispívat do této knihovny, přečtěte si průvodce pro přispívání a přečtěte si další informace o tom, jak sestavit a otestovat kód.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-03-18