Azure Web PubSub-serviceclientbibliotheek voor JavaScript - versie 1.1.1

  • Artikel

De 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 over publiceren/abonneren tussen server en clients of tussen clients vereist zijn, kan gebruikmaken van de Azure Web PubSub-service. Traditionele realtime-functies waarvoor vaak polling van server vereist is of HTTP-aanvragen moeten worden ingediend, kunnen ook gebruikmaken van de Azure Web PubSub-service.

U kunt deze bibliotheek in de app-server 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.
  • Gebruikers en verbindingen in groepen indelen.
  • Verbindingen sluiten
  • Machtigingen verlenen, intrekken en controleren voor een bestaande verbinding

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

Broncode | Pakket (NPM) | API-referentiedocumentatie | Productdocumentatie | Monsters

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

1. Installeer het @azure/web-pubsub pakket

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 ook verifiëren WebPubSubServiceClient 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. @azure/identity De afhankelijkheid installeren
npm install @azure/identity
  1. Werk de broncode bij voor het gebruik van DefaultAzureCredential:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

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

Belangrijkste concepten

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 is geslaagd, wordt een unieke verbindings-id toegewezen aan deze verbinding door de Web PubSub-service.

Hub

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 behoort deze tijdens de levensduur 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 op elk gewenst moment een clientverbinding toevoegen aan een groep of de clientverbinding uit de groep verwijderen. Wanneer een klant bijvoorbeeld deelneemt aan een chatruimte of wanneer een klant 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 via 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 PubSub voor 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 een 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>");

Het onbewerkte HTTP-antwoord voor een bewerking openen

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

Problemen oplossen

Logboeken inschakelen

U kunt de volgende omgevingsvariabele instellen om de logboeken voor foutopsporing op te halen wanneer u deze bibliotheek gebruikt.

  • Logboeken voor foutopsporing ophalen uit de SignalR-clientbibliotheek
export AZURE_LOG_LEVEL=verbose

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.

Livetracering

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

Volgende stappen

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

Bijdragen

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