JavaScript SDK för Azure Web PubSub

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.

Det finns två bibliotek som erbjuds för JavaScript: tjänstklientbiblioteket och expressmellanprogram. Följande avsnitt innehåller mer information om dessa bibliotek.

• Tjänstklientbibliotek
• Expressmellanprogram

Azure Web PubSub-tjänstklientbibliotek för JavaScript

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

• 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

Exempel på källkodspaket (NPM) | API-referensdokumentation | Produktdokumentation | |

Komma igång

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

• LTS-versioner av Node.js

Förutsättningar

• En Azure-prenumeration.
• En befintlig Azure Web PubSub-tjänstinstans.

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 med hjälp av WebPubSubServiceClient 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 med hjälp av WebPubSubServiceClient Microsoft Entra-ID

1. Installera beroendet @azure/identity

npm install @azure/identity

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

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

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

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

// 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 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: FullOperationResponse): void {
  console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient(
  "<ConnectionString>",
  "<hubName>"
);
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Felsökning av tjänstklient

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 Azure Web PubSub-klientbiblioteket

export AZURE_LOG_LEVEL=verbose

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Livespårning

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

Azure Web PubSub CloudEvents-hanterare för Express

När en WebSocket-anslutning ansluter omvandlar Web PubSub-tjänsten anslutningslivscykeln och meddelanden till händelser i CloudEvents-format. Det här biblioteket innehåller ett expressmellanprogram för att hantera händelser som representerar WebSocket-anslutningens livscykel och meddelanden, enligt diagrammet nedan:

Exempel på källkodspaket (NPM) | API-referensdokumentation | Produktdokumentation | |

Komma igång

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

• LTS-versioner av Node.js
• Express version 4.x.x eller senare

Förutsättningar

• En Azure-prenumeration.
• En befintlig Azure Web PubSub-slutpunkt.

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

npm install @azure/web-pubsub-express

2. Skapa en WebPubSubEventHandler

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Expressexempel

connect Hantera begäran och tilldela<userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>",
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"],
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Tillåt endast angivna slutpunkter

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com",
  ],
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Ange sökväg för anpassad händelsehanterare

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "/customPath1",
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Ange och läsa anslutningstillstånd

const express = require("express");

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

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  },
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

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 Azure Web PubSub-klientbiblioteket

export AZURE_LOG_LEVEL=verbose

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

Livespårning

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

Nästa steg

Använd dessa resurser för att börja skapa ett eget program: