Delen via

Azure Web PubSub-serviceclientbibliotheek voor JavaScript - versie 1.1.3

  • Artikel

Azure Web PubSub-service is een door Azure beheerde service waarmee ontwikkelaars eenvoudig webtoepassingen kunnen bouwen met realtime-functies en een patroon voor publiceren/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

Meer informatie over de termen die hier worden gebruikt, worden beschreven in sectie Belangrijke concepten.

API-referentiedocumentatie voor broncodePackage (NPM)ProductdocumentatieVoorbeelden

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

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

npm install @azure/web-pubsub

2. Een WebPubSubServiceClient maken en verifiëren

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

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

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

const { WebPubSubServiceClient, AzureKeyCredential } = require("@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 @azure/identity-afhankelijkheid installeren
npm install @azure/identity
  1. Werk de broncode bij om DefaultAzureCredentialte gebruiken:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

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

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

Berichten uitzenden naar alle verbindingen in een hub

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

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

Zie OData-filtersyntaxis voor Azure Web PubSubvoor meer informatie over filter syntaxis.

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

Berichten verzenden naar alle verbindingen in een groep

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

Berichten verzenden naar alle verbindingen voor een gebruiker

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

Controleer of de groep verbinding heeft

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

Toegang tot het onbewerkte HTTP-antwoord voor een bewerking

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

Probleemoplossing

Logboeken inschakelen

U kunt de volgende omgevingsvariabele instellen om de logboeken voor foutopsporing op te halen bij het gebruik van deze bibliotheek.

  • Foutopsporingslogboeken ophalen uit de SignalR-clientbibliotheek
export AZURE_LOG_LEVEL=verbose

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

Live Trace

Gebruik Live Trace vanuit de Web PubSub-serviceportal om het liveverkeer weer te geven.

Volgende stappen

Bekijk de voorbeelden map 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.