Azure Web PubSub-tjänstens klientbibliotek för JavaScript – version 1.2.0

2025-05-15

Azure Web PubSub-tjänsten är en Azure-hanterad tjänst som hjälper utvecklare att enkelt skapa webbprogram med realtidsfunktioner och publiceringsprenumerationsmönster. Alla scenarion som kräver publiceringsprenumerationsmeddelanden i realtid mellan server och klienter eller mellan klienter kan använda Azure Web PubSub-tjänsten. Traditionella realtidsfunktioner som ofta kräver avsökning från servern eller skicka HTTP-begäranden kan också använda Azure Web PubSub-tjänsten.

Du kan använda det här biblioteket på appserversidan för att hantera WebSocket-klientanslutningarna, enligt diagrammet nedan:

spill .

Skicka meddelanden till hubbar och grupper.
Skicka meddelanden till vissa användare och anslutningar.
Organisera användare och anslutningar i grupper.
Stäng anslutningar
Bevilja, återkalla och kontrollera behörigheter för en befintlig anslutning

Information om de termer som används här beskrivs i avsnittet Viktiga begrepp.

| Package (NPM) | API-referensdokumentation | Produktdokumentation | Exempel

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js

Förutsättningar

En prenumeration för Azure.
En befintlig Azure Web PubSub-tjänstinstans.

1. Installera `@azure/web-pubsub`-paketet

npm install @azure/web-pubsub

2. Skapa och autentisera en WebPubSubServiceClient

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

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

Du kan också autentisera WebPubSubServiceClient med hjälp av en slutpunkt och en AzureKeyCredential:

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

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

Eller autentisera WebPubSubServiceClient med hjälp av Azure Active Directory-

Installera @azure/identity beroende

npm install @azure/identity

Uppdatera källkoden så att den använder DefaultAzureCredential:

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

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

Viktiga begrepp

Samband

En anslutning, även kallad klient- eller klientanslutning, representerar en enskild WebSocket-anslutning som är ansluten till Web PubSub-tjänsten. När anslutningen har anslutits tilldelas ett unikt anslutnings-ID till den här anslutningen av Web PubSub-tjänsten.

Nav

En hubb är ett logiskt begrepp för en uppsättning klientanslutningar. Vanligtvis använder du en hubb för ett syfte, till exempel en chatthubb eller en meddelandehubb. När en klientanslutning skapas ansluter den till en hubb och under dess livslängd tillhör den hubben. Olika program kan dela en Azure Web PubSub-tjänst med hjälp av olika hubbnamn.

Grupp

En grupp är en delmängd av anslutningar till hubben. Du kan lägga till en klientanslutning till en grupp eller ta bort klientanslutningen från gruppen när du vill. När en klient till exempel ansluter till ett chattrum eller när en klient lämnar chattrummet kan det här chattrummet betraktas som en grupp. En klient kan ansluta till flera grupper och en grupp kan innehålla flera klienter.

Användare

Anslutningar till Web PubSub kan tillhöra en användare. En användare kan ha flera anslutningar, till exempel när en enskild användare är ansluten över flera enheter eller flera webbläsarflikar.

Meddelande

När klienten är ansluten kan den skicka meddelanden till det överordnade programmet eller ta emot meddelanden från det överordnade programmet via WebSocket-anslutningen.

Exempel

Hämta åtkomsttoken för en klient för att starta WebSocket-anslutningen

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"] });

Skicka meddelanden till alla anslutningar i en hubb

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

Skicka meddelanden till alla anslutningar i en hubb med OData-filtersyntax

Information om filter syntax finns i OData-filtersyntax för 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)`,
});

Skicka meddelanden till alla anslutningar i en grupp

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

Skicka meddelanden till alla anslutningar för en användare

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

Kontrollera om gruppen har någon anslutning

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

Få åtkomst till HTTP-råsvaret för en åtgärd

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

Felsökning

Aktivera loggar

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info.

export AZURE_LOG_LEVEL=verbose

Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i @azure/logger-paketdokumenten.

Livespårning

Använd Live Trace- från webbportalen för PubSub-tjänsten för att visa livetrafiken.

Nästa steg

Ta en titt på exempel katalog för detaljerade exempel på hur du använder det här biblioteket.

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Microsoft Azure SDK för Javascript

Feedback

Var den här sidan till hjälp?