Sdílet prostřednictvím

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

  • Článek

Služba Azure Web PubSub je spravovaná služba 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. Službu Azure Web PubSub může použít jakýkoli scénář, který vyžaduje zasílání zpráv publikování a odběru v reálném čase mezi serverem a klienty nebo mezi klienty. 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é využívat službu Azure Web PubSub.

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

přetečení.

  • Odesílání zpráv do center a skupin
  • Posí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 .

Zdrojový kód | Balíček (NPM) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky

Začínáme

Aktuálně podporovaná prostředí

Požadavky

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

npm install @azure/web-pubsub

2. Vytvoření a ověření klienta 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 službu WebPubSubServiceClient pomocí Azure Active Directory.

  1. @azure/identity Instalace závislosti
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 připojení klienta nebo klienta, představuje individuální připojení WebSocket připojené ke službě Web PubSub. Po úspěšném připojení přiřadí služba Web PubSub k tomuto připojení jedinečné ID připojení.

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 rozbočovači a během své ž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.

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

Připojení k web pubsub můžou 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.

Zpráva

Když je klient připojený, může odesílat zprávy do nadřazené aplikace nebo přijímat zprávy z nadřazené 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 filter syntaxi najdete v tématu Syntaxe filtru OData pro Azure 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 do všech připojení 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);

Zkontrolujte, jestli má skupina 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í potíží

Povolení protokolů

Pokud použijete tuto knihovnu, můžete nastavit následující proměnnou prostředí, abyste získali protokoly ladění.

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

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

Živé trasování

K zobrazení živého provozu použijte živé trasování z portálu služby Web PubSub.

Další kroky

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

Přispívání

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