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

Služba Azure Web PubSub je služba spravovaná 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:

.

• 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 pojmech jsou popsány v části Klíčové pojmy .

Zdrojový kód | Balíček (NPM) | Referenční dokumentace | k rozhraní APIDokumentace | k výrobkuVzorky

Začínáme

Aktuálně podporovaná prostředí

• LTS verze Node.js

Požadavky

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

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

npm install @azure/web-pubsub

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

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

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

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

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

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

Nebo ověřte pomocí WebPubSubServiceClientAzure Active Directory

1. Instalace @azure/identity závislosti

npm install @azure/identity

2. Aktualizujte zdrojový kód tak, aby používal:DefaultAzureCredential

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

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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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"] });

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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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.

import { WebPubSubServiceClient, odata } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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ě

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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í

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

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

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

function onResponse(rawResponse) {
  console.log(rawResponse);
}

await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Řešení problémů

Povolení protokolů

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

export AZURE_LOG_LEVEL=verbose

Případně můžete protokolování povolit za běhu voláním setLogLevel v @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í

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

Související projekty

• Microsoft Azure SDK pro JavaScript