Sdílet prostřednictvím

Klientská knihovna Web PubSub pro JavaScript

  • Článek

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

Jakýkoli scénář, který vyžaduje zasílání zpráv v reálném čase mezi serverem a klienty nebo mezi klienty podle vzorů publikování a odběru, může být výhodné z použití web PubSub. Vývojáři už nemusí dotazovat server odesíláním opakovaných požadavků HTTP v intervalech, což je plýtvání a obtížně škálovatelné.

Jak je znázorněno na diagramu níže, vaši klienti navazují připojení WebSocket k vašemu prostředku Web PubSub. Tato klientská knihovna:

  • zjednodušuje správu připojení klientů.
  • zjednodušuje odesílání zpráv mezi klienty.
  • automatické opakování po nezamýšleném ukončení připojení klienta
  • spolehlivě doručuje zprávy v počtu a pořadí po zotavení z výpadku připojení

Přetečení

Podrobnosti o zde použitých termínech jsou popsány v části Klíčové koncepty .

Tato knihovna je hostovaná v NPM.

Začínáme

Aktuálně podporovaná prostředí

Požadavky

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

npm install @azure/web-pubsub-client

2. Připojte se k prostředku Web PubSub.

Klient používá adresu URL klientského přístupu k připojení a ověření se službou, 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 pro klientský přístup. Pro účely tohoto rychlého startu můžete jeden zkopírovat a vložit z webu Azure Portal, jak je znázorněno níže. (V produkčním prostředí klienti obvykle získají adresu URL pro klientský přístup na vašem aplikačním serveru. Podrobnosti najdete níže .

get_client_url

Jak je znázorněno na diagramu výše, klient má oprávnění odesílat zprávy konkrétní skupině s názvem "skupina1" a připojit se k ní.

// 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. Připojení ke skupinám

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

// ...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. Odeslání zpráv skupině

// ...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říklady

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

  1. Když se klient úspěšně připojí k vašemu prostředku Web PubSub, aktivuje se connected událost .
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Když se klient odpojí a nepodaří se obnovit připojení, disconnected aktivuje se událost.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. Událost stopped se aktivuje, když se klient odpojí a klient se přestane pokoušet o opětovné připojení. K tomu obvykle dochází po client.stop() zavolání nebo autoReconnect zakázání nebo dosažení zadaného limitu pro pokus o opětovné připojení. Pokud chcete klienta restartovat, můžete volat client.start() v události zastaveno.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Programové vygenerování adresy URL klientského přístupu pomocí serveru vyjednávání

V produkčním prostředí klienti obvykle načítají adresu URL klientského přístupu z aplikačního serveru. Server obsahuje připojovací řetězec k vašemu prostředku Web PubSub a vygeneruje adresu URL klientského přístupu s pomocí z knihovny @azure/web-pubsubserveru .

1. Aplikační server

Následující fragment kódu je příkladem aplikačního serveru, který /negotiate zveřejňuje cestu a vrací adresu URL pro klientský přístup.

// 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. Na straně klienta

Níže uvedený fragment kódu je příkladem na straně klienta.

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

Úplný kód této ukázky najdete v prohlížeči samples-browser.

Klient využívá zprávy z aplikačního serveru nebo z připojených skupin.

Klient může přidávat zpětná volání pro zpracování zpráv z vašeho aplikačního serveru nebo skupin. Upozorňujeme, že v group-message případě, že klient může přijímat pouze zprávy skupiny, ke kterým 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}`);
});

Zpracování selhání opětovného připojení

Když se klient odpojí a nepodaří se ho obnovit, všechny kontexty skupin se vyčistí ve vašem prostředku Web PubSub. To znamená, že když se klient znovu připojí, musí se znovu připojit ke skupinám. Ve výchozím nastavení má autoRejoinGroup klient možnost povolenou.

Měli byste ale vědět o omezeních autoRejoinGroup, která má.

  • Klient se může znovu připojit pouze ke skupinám, ke kterým byl původně připojen kódem klienta, a ne kódem na straně serveru.
  • Operace opětovného připojení ke skupině můžou selhat z různých důvodů, například klient nemá oprávnění k připojení ke skupinám. V takových případech je potřeba přidat zpětné volání, které by toto selhání zvládlo.
// 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 opakování. Konfiguraci můžete provést prostřednictvím .messageRetryOptions Pokud všechna opakování selhala, vyvolá se chyba. Opakování můžete pokračovat předáním stejného ackId opakování jako v předchozích opakováních, aby služba Web PubSub mohl deduplikovat operaci.

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

Zadání dílčího protokolu

Můžete změnit dílčí protokol tak, aby ho používal klient. Ve výchozím nastavení klient používá json.reliable.webpubsub.azure.v1. Můžete použít json.reliable.webpubsub.azure.v1 nebo json.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() });

Klíčové koncepty

Připojení

Připojení, označované také jako připojení klienta nebo klienta, představuje individuální připojení WebSocket připojené k podsíti Web PubSub. Po úspěšném připojení přiřadí tomuto připojení web PubSub jedinečné ID připojení. Každý z nich WebPubSubClient vytváří své vlastní exkluzivní připojení.

Obnovovací

Pokud se klient používající spolehlivé protokoly odpojí, nový protokol WebSocket se pokusí vytvořit pomocí ID připojení ztraceného připojení. Pokud se nové připojení WebSocket úspěšně připojí, připojení se obnoví. Po celou dobu odpojení klienta si služba zachová kontext klienta i všechny zprávy, ke kterým byl klient přihlášen k odběru, a když se klient obnoví, služba odešle tyto zprávy klientovi. Pokud služba vrátí kód 1008 chyby WebSocket nebo pokus o obnovení trvá déle než 30 sekund, obnovení se nezdaří.

Znovu připojit

K opětovnému připojení dojde, když se připojení klienta přeruší a nepodaří se ho obnovit. Při opětovném připojení se spustí nové připojení a nové připojení má nové ID připojení. Na rozdíl od obnovení služba považuje znovu připojeného klienta za nové připojení klienta. Připojení klienta se musí znovu připojit ke skupinám. Ve výchozím nastavení se klientská knihovna po opětovném připojení ke skupinám znovu připojí.

Rozbočovač

Centrum je logický koncept sady klientských připojení. Obvykle se používá jedno centrum pro jeden účel, například centrum chatu nebo centrum oznámení. Když se vytvoří připojení klienta, připojí se k rozbočovači a během své životnosti patří do tohoto centra. Různé aplikace můžou sdílet jednu webovou pubsub pomocí různých názvů center.

Group (Skupina)

Skupina je podmnožinou připojení k centru. Kdykoliv můžete přidat připojení klienta ke skupině nebo ho ze skupiny odebrat. Například když se klient připojí k chatovací místnosti nebo když klient opustí chatovací místnost, lze tuto chatovací 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ů.

Uživatel

Connections 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ý na více zařízeních nebo na více kartách prohlížeče.

Životnost klienta

Každý z klientů Web PubSub je bezpečný pro ukládání do mezipaměti a je používán jako jednoznačné po celou dobu životnosti aplikace. Registrovaná zpětná volání událostí sdílejí stejnou životnost s klientem. To znamená, že zpětná volání můžete kdykoli přidat nebo odebrat a stav registrace se po opětovném připojení nebo zastavení klienta nezmění.

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu používat v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

Poradce při potížích

  • Povolení protokolů

    Pokud chcete při použití této knihovny získat protokoly ladění, můžete nastavit následující proměnnou prostředí.

export AZURE_LOG_LEVEL=verbose

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k balíčkům @azure/protokolovacího nástroje.

Další materiály

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.