Sdílet prostřednictvím

Klientská knihovna služby Azure Web PubSub pro JavaScript – verze 1.1.3

  • Článek

služba Azure Web PubSub je služba spravovaná v Azure, která vývojářům pomáhá snadno vytvářet webové aplikace s funkcemi v reálném čase a vzorem publikování a odběru. Jakýkoli scénář, který vyžaduje zasílání zpráv publikování a odběru v reálném čase mezi servery a klienty nebo mezi klienty, může používat službu Azure Web PubSub. Tradiční funkce v reálném čase, které často vyžadují dotazování ze serveru nebo odesílání požadavků HTTP, můžou také používat službu Azure Web PubSub.

Tuto knihovnu můžete použít na straně aplikačního serveru ke správě připojení klienta WebSocket, jak je znázorněno na následujícím diagramu:

přetečení .

  • Odesílání zpráv do center a skupin
  • Odesílání zpráv konkrétním uživatelům a připojením
  • Uspořádejte uživatele a připojení do skupin.
  • Zavření připojení
  • Udělení, odvolání a kontrola oprávnění pro existující připojení

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

Referenční dokumentace k rozhraníAPI zdrojového kódubalíčku (NPM)ukázky produktu

Začínáme

Aktuálně podporovaná prostředí

Požadavky

  • Předplatné Azure.
  • Existující instance služby Azure Web PubSub.

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

npm install @azure/web-pubsub

2. Vytvoření a ověření WebPubSubServiceClient

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

Můžete také ověřit WebPubSubServiceClient pomocí koncového bodu a AzureKeyCredential:

const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");

const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Nebo ověřte WebPubSubServiceClient pomocí azure Active Directory

  1. Instalace závislosti @azure/identity
npm install @azure/identity
  1. Aktualizujte zdrojový kód tak, aby používal DefaultAzureCredential:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Klíčové koncepty

Připojení

Připojení, označované také jako klient nebo připojení klienta, představuje individuální připojení WebSocket připojené ke službě Web PubSub. Po úspěšném připojení je k tomuto připojení přiřazeno jedinečné ID připojení službou Web PubSub.

Rozbočovač

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

Skupina

Skupina je podmnožinou připojení k centru. Ke skupině můžete přidat připojení klienta nebo ho z této skupiny kdykoli odebrat. Když se například klient připojí k chatovací místnosti nebo když klient opustí chatovací místnost, může být tato chatovací místnost považována za skupinu. Klient se může připojit k více skupinám a skupina může obsahovat více klientů.

Uživatel

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

Zpráva

Když je klient připojený, může odesílat zprávy do upstreamové aplikace nebo přijímat zprávy z upstreamové aplikace prostřednictvím připojení WebSocket.

Příklady

Získání přístupového tokenu pro klienta pro spuštění připojení WebSocket

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();

// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });

// Or get the access token that the client will join group GroupA when it connects using the access token
token = await serviceClient.getClientAccessToken({ userId: "user1", groups: [ "GroupA" ] });

// return the token to the WebSocket client

Vysílání zpráv pro všechna připojení v centru

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);

Odesílání zpráv do všech připojení v centru pomocí syntaxe filtru OData

Podrobnosti o syntaxi filter najdete v tématu syntaxe filtru OData proAzure Web PubSub .

const { WebPubSubServiceClient, odata } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message to anonymous connections
await serviceClient.sendToAll(
  { message: "Hello world!" },
  { filter: "userId eq null" }
  );

// Send a text message to connections in groupA but not in groupB
const groupA = 'groupA';
const groupB = 'groupB';
await serviceClient.sendToAll(
  "Hello world!",
  { 
    contentType: "text/plain",
    // use plain text "'groupA' in groups and not('groupB' in groups)"
    // or use the odata helper method
    filter: odata`${groupA} in groups and not(${groupB} in groups)` 
  });

Odesílání zpráv všem připojením ve skupině

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// Add user to the group
await groupClient.addUser("user1");

// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);

Odesílání zpráv všem připojením pro uživatele

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);

Kontrola, jestli skupina obsahuje nějaké připojení

const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const WebSocket = require("ws");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });

// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");

Přístup k nezpracované odpovědi HTTP pro operaci

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

function onResponse(rawResponse) {
  console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Řešení problémů

Povolení protokolů

Následující proměnnou prostředí můžete nastavit tak, aby při používání této knihovny získala protokoly ladění.

  • Získání protokolů ladění z klientské knihovny SignalR
export AZURE_LOG_LEVEL=verbose

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

Živé trasování

Pomocí živého trasování z portálu služby Web PubSub zobrazte živý provoz.

Další kroky

Podrobné příklady použití této knihovny najdete v ukázkách adresáři.

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.