Delen via

Azure Web PubSub-serviceclientbibliotheek voor JavaScript - versie 1.2.0

Azure Web PubSub-service is een door Azure beheerde service waarmee ontwikkelaars eenvoudig webtoepassingen kunnen bouwen met realtime functies en een patroon voor publiceren en abonneren. Elk scenario waarvoor realtime berichten voor publiceren/abonneren tussen server en clients of clients zijn vereist, kunnen de Azure Web PubSub-service gebruiken. Traditionele realtime-functies die vaak polling vereisen van de server of het verzenden van HTTP-aanvragen, kunnen ook gebruikmaken van de Azure Web PubSub-service.

U kunt deze bibliotheek aan de serverzijde van uw app gebruiken om de WebSocket-clientverbindingen te beheren, zoals wordt weergegeven in het onderstaande diagram:

overloop .

  • Berichten verzenden naar hubs en groepen.
  • Berichten verzenden naar bepaalde gebruikers en verbindingen.
  • Organiseer gebruikers en verbindingen in groepen.
  • Verbindingen sluiten
  • Machtigingen voor een bestaande verbinding verlenen, intrekken en controleren

Details over de termen die hier worden gebruikt, worden beschreven in de sectie Belangrijkste concepten .

Broncode | Pakket (NPM) | Documentatie voor | API-referentieProduct documentatie | Monsters

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

1. Het @azure/web-pubsub-pakket installeren

npm install @azure/web-pubsub

2. Een WebPubSubServiceClient maken en verifiëren

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

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

U kunt de WebPubSubServiceClient ook verifiëren met behulp van een eindpunt en een AzureKeyCredential:

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

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

Of verifieer de WebPubSubServiceClient met behulp van Azure Active Directory

  1. De afhankelijkheid installeren @azure/identity
npm install @azure/identity
  1. Werk de broncode bij om te gebruiken DefaultAzureCredential:
import { DefaultAzureCredential } from "@azure/identity";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

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

Sleutelbegrippen

Verbinding

Een verbinding, ook wel een client- of clientverbinding genoemd, vertegenwoordigt een afzonderlijke WebSocket-verbinding die is verbonden met de Web PubSub-service. Wanneer de verbinding tot stand is gebracht, wordt er een unieke verbindings-id toegewezen aan deze verbinding door de Web PubSub-service.

Naaf

Een hub is een logisch concept voor een set clientverbindingen. Meestal gebruikt u één hub voor één doel, bijvoorbeeld een chathub of een Notification Hub. Wanneer een clientverbinding wordt gemaakt, maakt deze verbinding met een hub en gedurende de levensduur behoort deze tot die hub. Verschillende toepassingen kunnen één Azure Web PubSub-service delen met behulp van verschillende hubnamen.

Groep

Een groep is een subset van verbindingen met de hub. U kunt een clientverbinding toevoegen aan een groep of de clientverbinding verwijderen uit de groep, op elk gewenst moment. Wanneer een client bijvoorbeeld deelneemt aan een chatruimte of wanneer een client de chatruimte verlaat, kan deze chatruimte worden beschouwd als een groep. Een client kan lid worden van meerdere groepen en een groep kan meerdere clients bevatten.

Gebruiker

Verbindingen met Web PubSub kunnen tot één gebruiker behoren. Een gebruiker kan meerdere verbindingen hebben, bijvoorbeeld wanneer één gebruiker is verbonden op meerdere apparaten of meerdere browsertabbladen.

Bericht

Wanneer de client is verbonden, kan deze berichten verzenden naar de upstream-toepassing of berichten ontvangen van de upstream-toepassing via de WebSocket-verbinding.

Voorbeelden

Het toegangstoken voor een client ophalen om de WebSocket-verbinding te starten

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

Berichten uitzenden naar alle verbindingen in een hub

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

Berichten verzenden naar alle verbindingen in een hub met de syntaxis van het OData-filter

Zie voor meer informatie over filter de syntaxis OData-filter voor 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)`,
});

Berichten verzenden naar alle verbindingen in een groep

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

Berichten verzenden naar alle verbindingen voor een gebruiker

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

Controleer of de groep verbinding heeft

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

Toegang tot het onbewerkte HTTP-antwoord voor een bewerking

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

Probleemoplossing

Logboeken inschakelen

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info.

export AZURE_LOG_LEVEL=verbose

U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Live traceren

Gebruik Live Trace van de Web PubSub-serviceportal om het live verkeer weer te geven.

Volgende stappen

Bekijk de map met voorbeelden voor gedetailleerde voorbeelden over het gebruik van deze bibliotheek.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.