Azure Web PubSub-tjänstklientbibliotek för JavaScript – version 1.1.3

  • Artikel

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

Förutsättningar

1. Installera @azure/web-pubsub-paketet

npm install @azure/web-pubsub

2. Skapa och autentisera en WebPubSubServiceClient

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

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

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

const { WebPubSubServiceClient, AzureKeyCredential } = require("@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-

  1. Installera @azure/identity beroende
npm install @azure/identity
  1. Uppdatera källkoden så att den använder DefaultAzureCredential:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

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

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

Skicka meddelanden till alla anslutningar i en hubb

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

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

Information om filter syntax finns i OData-filtersyntax för Azure Web PubSub.

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

Skicka meddelanden till alla anslutningar i en grupp

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

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

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

Kontrollera om gruppen har någon anslutning

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

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

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

Felsökning

Aktivera loggar

Du kan ange följande miljövariabel för att hämta felsökningsloggarna när du använder det här biblioteket.

  • Hämta felsökningsloggar från SignalR-klientbiblioteket
export AZURE_LOG_LEVEL=verbose

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.